@cosmicdrift/kumiko-framework 0.377.0 → 0.379.0

package/dist/engine/boot-validator/screens.js

@@ -18,6 +18,7 @@ import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js"
 import { explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../screen-helpers.js";
 import { metricField } from "../types/index.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
+import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
 function isRowClickAction(action) {
     return (action.kind === "navigate" || action.kind === "drawer") && action.rowClick === true;
@@ -182,21 +183,25 @@ function validateRowActionNavigateParams(featureName, screenId, screenType, scre
         return;
     if (target.screen.type === "dashboard") {
         const targetDescriptor = action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
-        const filter = target.screen.filter;
-        if (filter === undefined) {
+        const { filter, record, timeRange } = target.screen;
+        const readIds = [filter?.id, record?.param, timeRange?.id].filter((id) => id !== undefined);
+        if (readIds.length === 0) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
                 `params on navigate-target ${targetDescriptor} (dashboard) — target dashboard declares no ` +
-                `filter — params would be a no-op. Remove the params extractor, or add a \`filter\` to the ` +
+                `filter, time range or record binding — params would be a no-op. Remove the params extractor, or add a \`filter\` (or a \`record\` binding) to the ` +
                 `target dashboard so it has somewhere to read the value from.`);
         }
         const extractedKeys = rowFieldExtractorKeys(action.params);
-        if (!extractedKeys.includes(filter.id)) {
+        if (!readIds.some((id) => extractedKeys.includes(id))) {
+            const readDescriptor = filter !== undefined && readIds.length === 1
+                ? `filter id is "${filter.id}"`
+                : `URL params are [${readIds.join(", ")}]`;
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
                 `params [${extractedKeys.join(", ")}] on navigate-target ${targetDescriptor} (dashboard) whose ` +
-                `filter id is "${filter.id}" — none of the extracted keys match, so the filter would stay ` +
-                `unset. Fix the params extractor to produce a "${filter.id}" key, or remove it.`);
+                `${readDescriptor} — none of the extracted keys match, so the value would stay ` +
+                `unset. Fix the params extractor to produce one of these keys, or remove it.`);
         }
-        // skip: filter present and the extractor's keys cover it — valid dashboard deep-link.
+        // skip: a read id is present and the extractor's keys cover it — valid dashboard deep-link.
         return;
     }
     if (!readsNavigateParamsAsFormPrefill(target.screen, action.entityId, screenEntity)) {
@@ -945,6 +950,17 @@ function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandl
     const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
     validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, screen.fields, allowEmptyMintForm && fieldNames.size === 0);
     validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
+    if (screen.type === "actionForm") {
+        validateFormDerivations(feature.name, screenId, screen);
+        validateFormDerivationsEnforced(feature.name, screenId, screen, featureMap);
+    }
+    if (screen.type === "actionForm" &&
+        screen.load?.singleton === true &&
+        screen.load.idParam !== undefined) {
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both load.singleton: true ` +
+            `and load.idParam — singleton means the query picks the row from the caller's context, so ` +
+            `there is no record id to send under idParam. Remove idParam.`);
+    }
     validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
 // SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
@@ -1287,17 +1303,25 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     else if (action.kind === "clientAction") {
                         validateClientActionName(feature.name, screenId, "projectionList", "rowAction", action);
                     }
+                    else if (!allWriteHandlerQns.has(action.handler)) {
+                        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) rowAction "${action.id}" ` +
+                            `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                            `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+                    }
                 }
                 validateAtMostOneRowClick(feature.name, screenId, "projectionList", screen.rowActions);
             }
-            // Only drawer-kind and navigate actions that set tab are validated
-            // here — plain navigate (no tab) and writeHandler toolbarActions on
-            // projectionList have no boot check yet (pre-existing gap).
+            // Plain navigate toolbarActions (no tab) have no boot check yet.
             if (screen.toolbarActions !== undefined) {
                 for (const action of screen.toolbarActions) {
                     if (action.kind === "drawer") {
                         validateDrawerTargetAction(feature.name, screenId, "projectionList", "toolbarAction", action, feature.screens);
                     }
+                    else if (action.kind === "writeHandler" && !allWriteHandlerQns.has(action.handler)) {
+                        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) toolbarAction "${action.id}" ` +
+                            `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                            `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+                    }
                     if (action.kind === "navigate" && action.tab !== undefined) {
                         resolveRowActionNavigateTarget(feature.name, screenId, "projectionList", "toolbarAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
                     }
@@ -2066,7 +2090,7 @@ function validateDashboardScreen(featureName, screenId, screen, featureMap) {
             validateDashboardScreenPanel(featureName, screenId, panel, featureMap);
         }
         else if (panel.kind === "text") {
-            validateDashboardTextPanel(featureName, screenId, panel);
+            validateDashboardTextPanel(featureName, screenId, panel, featureMap);
         }
         else {
             validateDashboardQueryPanel(featureName, screenId, panel, featureMap);
@@ -2250,7 +2274,7 @@ export function validateDashboardScreenPanel(featureName, screenId, panel, featu
         throw new Error(`${context} fallback "${panel.fallback}" has its own visibleWhen; a fallback must always render.`);
     }
 }
-function validateDashboardTextPanel(featureName, screenId, panel) {
+function validateDashboardTextPanel(featureName, screenId, panel, featureMap) {
     const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) text-panel "${panel.id}"`;
     if (panel.blocks.length === 0) {
         throw new Error(`${context} has an empty blocks list. Add at least one block.`);
@@ -2261,6 +2285,20 @@ function validateDashboardTextPanel(featureName, screenId, panel) {
         if (block.kind === "list" && block.items.length === 0) {
             throw new Error(`${context} has a list block without items. Add items or remove the block.`);
         }
+        if (block.kind === "link")
+            validateDashboardTextLinkBlock(context, block, featureName, featureMap);
+    }
+}
+function validateDashboardTextLinkBlock(context, block, featureName, featureMap) {
+    const targetQn = resolveScreenTargetQn(featureName, block.screen);
+    const [targetFeatureName = "", , targetShortId = ""] = targetQn.split(":");
+    if (featureMap.get(targetFeatureName)?.screens[targetShortId] === undefined) {
+        throw new Error(`${context} link block screen "${block.screen}" does not resolve to a registered screen ` +
+            `(checked "${targetQn}"). Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`);
+    }
+    if (block.roles?.length === 0) {
+        throw new Error(`${context} link block "${block.screen}" has an empty roles list, which would hide it from everyone. ` +
+            `List the roles or omit roles.`);
     }
 }
 function validateDashboardPanelVisibleWhen(context, visibleWhen) {

package/dist/engine/build-config-feature-schema.js

@@ -46,6 +46,10 @@ const PROVIDER_PANEL_TITLE_ENTRY = {
     es: "Proveedor",
 };
 const PROVIDER_SECTION_TITLE_KEY = "config.settings.provider";
+// The empty option of a provider select means "no own provider, the platform handles it". A selector
+// names it through `<field label key>.platformDefault`, else this generic text applies.
+const PLATFORM_DEFAULT_LABEL_SUFFIX = ".platformDefault";
+const PLATFORM_DEFAULT_FALLBACK_KEY = "config.settings.provider.platformDefault";
 const SECRETS_SECTION_DESCRIPTION_KEY = "config.secrets.description";
 const audienceNavShortId = (scope) => `audience-${scope}`;
 // Generated post-boot, never via r.nav() — the boot validator exempts exactly these QNs (an app references one to place the settings group inline).
@@ -214,8 +218,8 @@ function buildFeatureNav(scope, feature, ordered, access, declaredTranslationKey
         access,
     };
 }
-// One configEdit screen + child-nav per feature; a tenant-scope selector owner
-// becomes a dashboard instead and its gated plugins get no entries of their own.
+// One configEdit screen + child-nav per feature; a tenant-scope selector owner folds its
+// gated plugins into its own screen (a dashboard when it carries extra panels).
 function buildFeatureScreensAndNavs(scope, visible, hub, gating, secretsAccess) {
     const out = { screens: [], navs: [], translations: {} };
     const ungated = visible.filter((v) => !gating.pluginFeatures.has(v.key.ownerFeature));
@@ -230,7 +234,7 @@ function buildFeatureScreensAndNavs(scope, visible, hub, gating, secretsAccess)
             out.navs.push(buildFeatureNav(scope, feature, ordered, access, hub.declaredTranslationKeys));
             continue;
         }
-        const ownerHub = buildSelectorOwnerDashboard(feature, ordered, access, plugins, gating.ownerPanelsByGroup.get(feature) ?? [], hub, secretsAccess);
+        const ownerHub = buildSelectorOwnerScreens(feature, ordered, access, plugins, gating.ownerPanelsByGroup.get(feature) ?? [], hub, secretsAccess);
         out.screens.push(...ownerHub.screens);
         out.navs.push(buildFeatureNav(scope, feature, ordered, ownerHub.access, hub.declaredTranslationKeys));
         Object.assign(out.translations, ownerHub.translations);
@@ -251,15 +255,19 @@ function assertUniquePanelIds(ownerGroup, panels) {
 // One form for the provider and the settings of every provider: a single save writes
 // all of it, so switching sections can't drop typed input. Each plugin's fields are
 // shown only while its provider is picked in the form; hidden fields are not saved.
-function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins, ownerPanels, hub, secretsAccess) {
-    const selectionScreenId = `${ownerGroup}-tenant-selection`;
+// Without extra panels the form is the owner's screen itself; with panels it sits
+// chromeless in a dashboard.
+function buildSelectorOwnerScreens(ownerGroup, ownerKeys, ownerAccess, plugins, ownerPanels, hub, secretsAccess) {
+    const hasPanels = ownerPanels.length > 0;
+    const selectionScreenId = hasPanels ? `${ownerGroup}-tenant-selection` : `${ownerGroup}-tenant`;
     const form = new ProviderFormBuilder(selectionScreenId, buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub, {
         description: EXTENSION_SELECTOR_HINT_KEY,
-        sectionTitle: PROVIDER_SECTION_TITLE_KEY,
+        ...(hasPanels && { sectionTitle: PROVIDER_SECTION_TITLE_KEY }),
     }));
     const accessRules = [ownerAccess];
     const translations = {};
-    translations[`screen:${selectionScreenId}.title`] = PROVIDER_PANEL_TITLE_ENTRY;
+    if (hasPanels)
+        translations[`screen:${selectionScreenId}.title`] = PROVIDER_PANEL_TITLE_ENTRY;
     Object.assign(translations, providerOptionTranslations(form.base, hub));
     for (const plugin of plugins) {
         const providerFieldId = form.fieldIdOfConfigKey(plugin.selectorQn);
@@ -279,7 +287,10 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
         }
     }
     const access = unionAccessRules(accessRules);
-    const selectionScreen = { ...form.build(access), dormant: true };
+    const providerForm = form.build(access);
+    if (!hasPanels)
+        return { screens: [providerForm], access, translations };
+    const selectionScreen = { ...providerForm, dormant: true };
     const dashboard = {
         id: `${ownerGroup}-tenant`,
         type: "dashboard",
@@ -726,6 +737,14 @@ function providerOptionTranslations(selectionScreen, hub) {
         const featureByPluginId = hub.selectorOptionFeatures.get(qn);
         if (featureByPluginId === undefined)
             continue;
+        const fieldLabelTranslationKey = selectionScreen.fieldLabels?.[fieldId];
+        const platformDefaultLabel = (fieldLabelTranslationKey !== undefined
+            ? hub.translationsByKey.get(`${fieldLabelTranslationKey}${PLATFORM_DEFAULT_LABEL_SUFFIX}`)
+            : undefined) ?? hub.translationsByKey.get(PLATFORM_DEFAULT_FALLBACK_KEY);
+        if (platformDefaultLabel !== undefined) {
+            out[`${fieldLabelKey(SETTINGS_HUB_FEATURE, CONFIG_EDIT_ENTITY, fieldId)}:option:`] =
+                platformDefaultLabel;
+        }
         for (const [pluginId, feature] of featureByPluginId) {
             const label = hub.translationsByKey.get(`${feature}.settings`);
             if (label === undefined)
@@ -738,8 +757,12 @@ function providerOptionTranslations(selectionScreen, hub) {
 }
 function deriveField(key, selectorPluginIds, screenKeys, fieldIdOf) {
     const def = key.def;
-    if (selectorPluginIds !== undefined)
-        return createSelectField({ options: selectorPluginIds });
+    if (selectorPluginIds !== undefined) {
+        return createSelectField({
+            options: selectorPluginIds.length > 0 ? ["", ...selectorPluginIds] : selectorPluginIds,
+            display: "radio",
+        });
+    }
     switch (def.type) {
         case "number":
             return createNumberField({

package/dist/engine/embedded-derived.d.ts

@@ -1,6 +1,6 @@
 import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "./types/index.ts";
 /** Computes a derived cell from its source values. Missing/non-numeric
- *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
+ *  sources: "multiply"/"percent" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every
  *  source is missing, return undefined (do not invent 0). Money cells are
  *  minor-unit integers — unit-agnostic arithmetic; `withDerivedCells` rounds

package/dist/engine/embedded-derived.js

@@ -1,6 +1,6 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 /** Computes a derived cell from its source values. Missing/non-numeric
- *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
+ *  sources: "multiply"/"percent" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every
  *  source is missing, return undefined (do not invent 0). Money cells are
  *  minor-unit integers — unit-agnostic arithmetic; `withDerivedCells` rounds
@@ -15,6 +15,12 @@ export function computeDerivedCellValue(op, values) {
         }
         return product;
     }
+    if (op === "percent") {
+        const [base, rate] = values;
+        if (values.length !== 2 || base === undefined || rate === undefined)
+            return undefined;
+        return (base * rate) / 100;
+    }
     if (values.every((value) => value === undefined))
         return undefined;
     const numeric = values.map((value) => value ?? 0);

package/dist/engine/feature-ui-extensions.js

@@ -1,6 +1,7 @@
 import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
+import { markExecutorManagedTable } from "../db/executor-managed-tables.js";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { LifecycleHookTypes } from "./constants.js";
 import { resolveName } from "./handler-helpers.js";
@@ -298,6 +299,9 @@ export function buildUiExtensionsMethods(state, name) {
                 throw new Error(`[Feature ${name}] Projection "${definition.name}" already registered. ` +
                     `Projection names must be unique per feature.`);
             }
+            if (typeof definition.table === "object" && definition.table !== null) {
+                markExecutorManagedTable(definition.table);
+            }
             state.projections[definition.name] = definition;
         },
         multiStreamProjection(definition) {

package/dist/engine/form-derivations.d.ts

@@ -0,0 +1,21 @@
+import type { FormFieldDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { FormFieldDerivation } from "./types/screen.ts";
+export type FormDerivationScreen = {
+    readonly fields: Readonly<Record<string, FormFieldDefinition>>;
+    readonly derive?: Readonly<Record<string, FormFieldDerivation>>;
+};
+/** Targets ordered so every derived source is computed before its reader. */
+export declare function orderFormDerivations(derive: Readonly<Record<string, FormFieldDerivation>>): readonly string[];
+/** True when `field` is a `listSum` without `whenEmpty` whose list has no
+ *  rows: the sum has nothing to add up, so the user types the value. */
+export declare function isFormDerivationInputMode(screen: FormDerivationScreen, values: unknown, field: string): boolean;
+/** True when `field` is only read as a `whenEmpty` operand of `listSum`
+ *  derivations whose lists all have rows: nothing reads it, so it is locked
+ *  rather than inviting an input that is silently dropped. */
+export declare function isUnusedFallbackOperand(screen: FormDerivationScreen, values: unknown, field: string): boolean;
+/** Recomputes every derived head field of an action form from its inputs.
+ *  Pure and client-safe: the renderer runs it live, the server runs it
+ *  again (`withFormDerivations`) and overwrites whatever the client sent.
+ *  Money operands are converted to minor units for the arithmetic and money
+ *  targets are written back as `{ amount, currency }` in major units. */
+export declare function applyFormDerivations(values: unknown, screen: FormDerivationScreen): unknown;

package/dist/engine/form-derivations.js

@@ -0,0 +1,175 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { computeDerivedCellValue, roundDerivedCellValue, withDerivedCells, } from "./embedded-derived.js";
+import { MINOR_UNIT_SCALE, toMinorUnits } from "./minor-units.js";
+function readMoneyOperand(raw) {
+    if (typeof raw === "number")
+        return { minor: toMinorUnits(raw), currency: undefined };
+    if (!isPlainObject(raw) || typeof raw["amount"] !== "number")
+        return undefined;
+    const currency = raw["currency"];
+    return {
+        minor: toMinorUnits(raw["amount"]),
+        currency: typeof currency === "string" && currency !== "" ? currency : undefined,
+    };
+}
+function readOperand(values, fields, name) {
+    const raw = values[name];
+    if (fields[name]?.type === "money") {
+        const money = readMoneyOperand(raw);
+        return { value: money?.minor, currency: money?.currency };
+    }
+    return { value: typeof raw === "number" ? raw : undefined, currency: undefined };
+}
+function dependenciesOf(derivation) {
+    if (derivation.op === "listSum") {
+        return derivation.whenEmpty === undefined ? [] : derivation.whenEmpty.from;
+    }
+    return derivation.from;
+}
+/** Targets ordered so every derived source is computed before its reader. */
+export function orderFormDerivations(derive) {
+    const ordered = [];
+    const state = new Map();
+    const visit = (name, path) => {
+        const derivation = derive[name];
+        // skip: plain input field, nothing to order
+        if (derivation === undefined)
+            return;
+        const status = state.get(name);
+        // skip: already ordered via another path
+        if (status === "done")
+            return;
+        if (status === "visiting") {
+            throw new Error(`Form derivation cycle: ${[...path, name].join(" -> ")}`);
+        }
+        state.set(name, "visiting");
+        for (const dependency of dependenciesOf(derivation))
+            visit(dependency, [...path, name]);
+        state.set(name, "done");
+        ordered.push(name);
+    };
+    for (const name of Object.keys(derive))
+        visit(name, []);
+    return ordered;
+}
+function isNonEmptyList(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+/** True when `field` is a `listSum` without `whenEmpty` whose list has no
+ *  rows: the sum has nothing to add up, so the user types the value. */
+export function isFormDerivationInputMode(screen, values, field) {
+    const derivation = screen.derive?.[field];
+    if (derivation === undefined || derivation.op !== "listSum")
+        return false;
+    if (derivation.whenEmpty !== undefined)
+        return false;
+    return !isPlainObject(values) || !isNonEmptyList(values[derivation.list]);
+}
+/** True when `field` is only read as a `whenEmpty` operand of `listSum`
+ *  derivations whose lists all have rows: nothing reads it, so it is locked
+ *  rather than inviting an input that is silently dropped. */
+export function isUnusedFallbackOperand(screen, values, field) {
+    const derive = screen.derive;
+    if (derive === undefined || derive[field] !== undefined)
+        return false;
+    let usedAsFallback = false;
+    for (const derivation of Object.values(derive)) {
+        if (derivation.op !== "listSum") {
+            if (derivation.from.includes(field))
+                return false;
+            continue;
+        }
+        if (derivation.whenEmpty?.from.includes(field) !== true)
+            continue;
+        if (!isPlainObject(values) || !isNonEmptyList(values[derivation.list]))
+            return false;
+        usedAsFallback = true;
+    }
+    return usedAsFallback;
+}
+function sumListCell(rows, listField, cell) {
+    const embedded = listField?.type === "embedded" ? listField : undefined;
+    let sum = 0;
+    for (const rawRow of rows) {
+        // Recompute the row's derived cells so a manipulated row value can't leak into the head.
+        const row = embedded?.derived === undefined
+            ? rawRow
+            : withDerivedCells(rawRow, embedded.derived, embedded.schema);
+        if (isPlainObject(row) && typeof row[cell] === "number")
+            sum += row[cell];
+    }
+    return sum;
+}
+function targetCurrency(field, current, sourceCurrency) {
+    if (isPlainObject(current) &&
+        typeof current["currency"] === "string" &&
+        current["currency"] !== "") {
+        return current["currency"];
+    }
+    if (sourceCurrency !== undefined)
+        return sourceCurrency;
+    if (field.type === "money" && field.currency.kind === "literal")
+        return field.currency.code;
+    return undefined;
+}
+/** Recomputes every derived head field of an action form from its inputs.
+ *  Pure and client-safe: the renderer runs it live, the server runs it
+ *  again (`withFormDerivations`) and overwrites whatever the client sent.
+ *  Money operands are converted to minor units for the arithmetic and money
+ *  targets are written back as `{ amount, currency }` in major units. */
+export function applyFormDerivations(values, screen) {
+    if (!isPlainObject(values))
+        return values;
+    const derive = screen.derive;
+    if (derive === undefined)
+        return values;
+    const result = { ...values };
+    for (const target of orderFormDerivations(derive)) {
+        const derivation = derive[target];
+        const targetField = screen.fields[target];
+        if (derivation === undefined || targetField === undefined)
+            continue;
+        let computed;
+        let sourceCurrency;
+        let ordinary;
+        if (derivation.op === "listSum") {
+            const rows = result[derivation.list];
+            if (isNonEmptyList(rows)) {
+                computed = sumListCell(rows, screen.fields[derivation.list], derivation.cell);
+            }
+            else if (derivation.whenEmpty === undefined) {
+                continue;
+            }
+            else {
+                ordinary = derivation.whenEmpty;
+            }
+        }
+        else {
+            ordinary = derivation;
+        }
+        if (ordinary !== undefined) {
+            const operands = ordinary.from.map((name) => readOperand(result, screen.fields, name));
+            sourceCurrency = operands.find((operand) => operand.currency !== undefined)?.currency;
+            computed = computeDerivedCellValue(ordinary.op, operands.map((operand) => operand.value));
+        }
+        if (computed === undefined) {
+            delete result[target];
+            continue;
+        }
+        if (targetField.type === "money") {
+            const minor = roundDerivedCellValue(computed, { type: "money" });
+            const currency = targetCurrency(targetField, result[target], sourceCurrency);
+            result[target] =
+                currency === undefined
+                    ? { amount: minor / MINOR_UNIT_SCALE }
+                    : { amount: minor / MINOR_UNIT_SCALE, currency };
+        }
+        else if (targetField.type === "decimal") {
+            result[target] = roundDerivedCellValue(computed, targetField);
+        }
+        else {
+            result[target] = computed;
+        }
+    }
+    return result;
+}

package/dist/engine/index.d.ts

@@ -45,6 +45,8 @@ export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, group
 export { type ChangelogEntry, type ChangelogType, compareVersions, type FeatureChangelog, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.ts";
 export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, type ManifestSystemEvent, serializeManifest, } from "./feature-manifest.ts";
 export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.ts";
+export type { FormDerivationScreen } from "./form-derivations.ts";
+export { applyFormDerivations, isFormDerivationInputMode } from "./form-derivations.ts";
 export { HANDLER_FIELD_REFERENCES_META_KEY, type HandlerFieldPathSegment, type HandlerFieldReference, type HandlerFieldReferenceAtPath, type HandlerFieldReferenceMeta, handlerFieldReference, handlerFieldReferences, readHandlerFieldReferences, } from "./handler-field-references.ts";
 export { resolveName, withResponseData } from "./handler-helpers.ts";
 export { i18nKey } from "./i18n-key.ts";
@@ -85,7 +87,8 @@ export { assertNotificationVariables, templateVariable, templateVariablesToZod,
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, requireTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.ts";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, type TransferAdjacency, type TransferEdge, type TransferEdgeLink, } from "./transfer-adjacency.ts";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.ts";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, BootOptionName, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityObjectDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookDefinition, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MaxPerTenantOptions, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreparedWriteEvent, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, ProviderPluginContext, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StackBootRequirement, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.ts";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, BootOptionName, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityObjectDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookDefinition, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MaxPerTenantOptions, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreparedWriteEvent, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, ProviderPluginContext, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StackBootRequirement, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TemplateImagesVariableDef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.ts";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.ts";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.ts";
 export { runValidation } from "./validation.ts";
+export { formDerivationsOfSchema, withFormDerivations } from "./with-form-derivations.ts";

package/dist/engine/index.js

@@ -40,6 +40,7 @@ export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, group
 export { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { buildManifestFromRegistry, serializeManifest, } from "./feature-manifest.js";
 export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
+export { applyFormDerivations, isFormDerivationInputMode } from "./form-derivations.js";
 export { HANDLER_FIELD_REFERENCES_META_KEY, handlerFieldReference, handlerFieldReferences, readHandlerFieldReferences, } from "./handler-field-references.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
@@ -80,3 +81,4 @@ export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTra
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export { runValidation } from "./validation.js";
+export { formDerivationsOfSchema, withFormDerivations } from "./with-form-derivations.js";

package/dist/engine/minor-units.d.ts

@@ -0,0 +1,2 @@
+export declare const MINOR_UNIT_SCALE = 100;
+export declare function toMinorUnits(amount: number): number;

package/dist/engine/minor-units.js

@@ -0,0 +1,8 @@
+// 2 decimal places (cents) — covers every currently-supported currency
+// (EUR/USD/GBP/...). No ISO-4217 minor-unit table yet (JPY=0, BHD=3) —
+// upgrade path once a currency needing a different scale actually lands.
+// Client-safe on purpose: db/money.ts pulls in engine runtime values.
+export const MINOR_UNIT_SCALE = 100;
+export function toMinorUnits(amount) {
+    return Math.round(amount * MINOR_UNIT_SCALE);
+}

package/dist/engine/registry-state.js

@@ -1,5 +1,6 @@
 import { applyEntityEvent } from "../db/apply-entity-event.js";
 import { assertBackingTableSuperset, deriveEntityTableMeta } from "../db/entity-table-meta.js";
+import { markExecutorManagedTable } from "../db/executor-managed-tables.js";
 import { asEntityTableMeta } from "../db/query.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { qualifyEntityName } from "./qualified-name.js";
@@ -20,6 +21,7 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
     const drizzleTable = backingTable !== undefined
         ? resolveBackingTable(entityName, entity, backingTable)
         : buildEntityTable(entityName, entity);
+    markExecutorManagedTable(drizzleTable);
     // applyEntityEvent gibt ApplyResult zurück; SingleStreamApplyFn erwartet
     // Promise<void>. Im rebuild-Pfad ist die Row irrelevant — wir discarden.
     const handler = async (event, tx) => {

package/dist/engine/registry-validate.js

@@ -476,8 +476,11 @@ export function validateProjectionApplyKeys(state) {
         //      or `jobRun` (BullMQ-callback-driven lifecycle, no executor).
         //      A "Shape-Anchor"-entity is no longer needed for this case.
         const isEventsOnlySource = !sources.every((src) => state.entityMap.has(src));
+        // An extension source may be a stream whose events the executor writes under a
+        // name that is no registered entity (document-extract); its auto-verbs count.
+        const extensionSources = projDef.extraSources ?? [];
         for (const src of rebuildSources) {
-            if (state.entityMap.has(src)) {
+            if (state.entityMap.has(src) || extensionSources.includes(src)) {
                 for (const verb of ENTITY_LIFECYCLE_VERBS)
                     validEventTypes.add(`${src}.${verb}`);
             }

package/dist/engine/schema-builder.js

@@ -236,12 +236,26 @@ export function fieldToZod(field, currencies, opts = {}) {
             // whether the key may be omitted at all is decided by buildInsertSchema
             // off the same flag. `minItems` overrides that default when set.
             let list = z.array(row);
-            const min = field.minItems ?? (field.required === true ? 1 : undefined);
-            if (min !== undefined)
-                list = list.min(min);
             if (field.maxItems !== undefined)
                 list = list.max(field.maxItems);
-            return list;
+            const min = field.minItems ?? (field.required === true ? 1 : undefined);
+            if (min === undefined)
+                return list;
+            // A custom issue rather than min(): other arrays (multiSelect) share zod's
+            // too_small and must not read "rows"; the bridge honours params.i18nKey.
+            return list.superRefine((rows, ctx) => {
+                // skip: the minimum is met, nothing to report
+                if (rows.length >= min)
+                    return;
+                ctx.addIssue({
+                    code: "custom",
+                    input: rows,
+                    params: {
+                        i18nKey: `errors.validation.list_min_rows.${min === 1 ? "one" : "other"}`,
+                        minimum: min,
+                    },
+                });
+            });
         }
         case "jsonb": {
             // Free-form jsonb — keys sind tenant-/runtime-defined. Validation

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

@@ -1,5 +1,6 @@
 import type { FieldDefinition, SelectFieldDef } from "./types/fields.ts";
 import type { ActionFormScreenDefinition, ConfigEditScreenDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, FieldCondition, FormatSpec, ListColumnSpec, ProjectionDetailScreenDefinition, ScreenDefinition, SecretMintScreenDefinition } from "./types/screen.ts";
+export declare const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
 export declare function explicitListScreenId(screen: ScreenDefinition): string | undefined;
 export declare function resolveNavParentScreen(screens: readonly ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
 export type EditLayoutScreen = ProjectionDetailScreenDefinition | EntityEditScreenDefinition | ActionFormScreenDefinition | ConfigEditScreenDefinition | SecretMintScreenDefinition;

package/dist/engine/screen-helpers.js

@@ -1,3 +1,6 @@
+// Entity name the renderer gives the synthesized entity of an actionForm, secretMint or confirm
+// step. It is not registered, so nothing server-side may treat it as a real entity.
+export const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
 // Every screen type carrying `listScreenId` declares it identically; centralizing
 // here keeps the switch the only place that grows for a new screen type.
 export function explicitListScreenId(screen) {