@cosmicdrift/kumiko-framework 0.377.0 → 0.378.0

package/agents/examples/delivery-notifications.md

@@ -16,7 +16,7 @@ Shows how a feature sends notifications to multiple channels (InApp + Email + Pu
 
 **Mail text is stored data:** The boot seed (`seedNotificationTemplates`) writes the declared `template` and `meta` into the template store as system templates. The email channel renders them with `renderer-mail-html`. A notification routed to email without `template` and `meta` fails its delivery.
 
-**Tenant override:** A tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`). The next mail for that tenant uses the override; the system text stays for everyone else.
+**Tenant override:** Only a SystemAdmin edits templates unless the app unlocks them. The app lists the mail in `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug, access: { roles: ["TenantAdmin"] } }] })`; then a tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`) and every other template is refused with 403. The next mail for that tenant uses the override; the system text stays for everyone else.
 
 **Sending:** The write handler calls `ctx.notify(type, { to, data })`. The `data` keys are the template variables; sending fails loudly when a required variable is missing.
 
@@ -137,7 +137,9 @@ const assignee = createTestUser({ id: 5, roles: ["Support"] });
 const features = [
   createConfigFeature(),
   createTenantFeature(),
-  createTemplateResolverFeature(),
+  createTemplateResolverFeature({
+    tenantEditable: [{ kind: "mail", slug: TICKET_ASSIGNED, access: { roles: ["TenantAdmin"] } }],
+  }),
   createRendererFoundationFeature(),
   createRendererMailHtmlFeature(),
   createDeliveryFeature(),
@@ -275,6 +277,27 @@ describe("delivery-notifications sample", () => {
     expect(email?.html).toContain("Tenant text: Printer on fire");
   });
 
+  test("a tenant admin may not override a mail the app did not list in tenantEditable", async () => {
+    const tenantAdmin = { ...admin, roles: ["TenantAdmin"] };
+
+    const error = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertTenant,
+      {
+        slug: "support:notify:ticket-closed",
+        kind: "mail",
+        locale: "en",
+        content: "<p>Closed</p>",
+        contentFormat: "html",
+        meta: { subject: "Closed" },
+        variableSchema: {},
+      },
+      tenantAdmin,
+    );
+
+    expect(error.code).toBe("access_denied");
+    expect(error.i18nKey).toBe("templateResolver.errors.templateNotTenantEditable");
+  });
+
   test("ticket without assignee skips notification (recipient returns null)", async () => {
     emailTransport.sent.length = 0;
     pushTransport.sent.length = 0;

package/agents/examples/embedded.md

@@ -27,6 +27,14 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
   `createEmbeddedListField`; its renderer receives `embeddedListCells`, so no
   custom screen component is required.
 
+- **Derived head totals** (`src/screens/invoice-receive.screen.ts`): an
+  `actionForm` declares `derive` so net, VAT, and gross follow the lines
+  (`listSum`), or follow a typed net and VAT rate while the list is empty
+  (`whenEmpty`, `percent`). The renderer shows them read-only and live; the
+  handler wraps its schema with `withFormDerivations(schema, screen)`
+  (`src/handlers/invoice-receive.write.ts`), so totals sent by the client are
+  replaced on the server.
+
 ## When to reach for it
 
 Use an embedded field or list when the nested data is created, changed, and
@@ -397,6 +405,74 @@ describe("invoice line items with select/reference/derived/totals metadata", ()
     expect(error).toBeDefined();
   });
 });
+
+// --- actionForm derive ---
+
+describe("invoice receive form derives its totals on the server", () => {
+  type ReceiveTotals = {
+    netTotal: { amount: number; currency: string };
+    vatTotal: { amount: number; currency: string };
+    grossTotal: { amount: number; currency: string };
+  };
+  const eur = (amount: number) => ({ amount, currency: "EUR" });
+  const head = { supplier: "Papier AG", invoiceNumber: "RE-2026-0042" };
+
+  test("with lines, manipulated client totals are replaced by the line sums", async () => {
+    const totals = await stack.http.writeOk<ReceiveTotals>(
+      "contacts:write:invoice:receive",
+      {
+        ...head,
+        lines: [
+          { description: "Paper", amount: 1005, vatRate: 19, vatAmount: 5 },
+          { description: "Toner", amount: 2000, vatRate: 7 },
+        ],
+        netTotal: eur(1),
+        vatTotal: eur(2),
+        grossTotal: eur(3),
+      },
+      admin,
+    );
+    expect(totals).toEqual({
+      netTotal: eur(30.05),
+      vatTotal: eur(3.31),
+      grossTotal: eur(33.36),
+    });
+  });
+
+  test("without lines, the typed net stays and VAT and gross are computed from the rate", async () => {
+    const totals = await stack.http.writeOk<ReceiveTotals>(
+      "contacts:write:invoice:receive",
+      { ...head, lines: [], netTotal: eur(100), vatRate: 19, vatTotal: eur(0), grossTotal: eur(0) },
+      admin,
+    );
+    expect(totals).toEqual({ netTotal: eur(100), vatTotal: eur(19), grossTotal: eur(119) });
+  });
+
+  test("a stale gross total is overwritten", async () => {
+    const totals = await stack.http.writeOk<ReceiveTotals>(
+      "contacts:write:invoice:receive",
+      {
+        ...head,
+        lines: [],
+        netTotal: eur(50),
+        vatRate: 20,
+        vatTotal: eur(0),
+        grossTotal: eur(999),
+      },
+      admin,
+    );
+    expect(totals.grossTotal).toEqual(eur(60));
+  });
+
+  test("a caller without the Admin role is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:receive",
+      { ...head, lines: [], netTotal: eur(50), vatRate: 20, vatTotal: eur(0), grossTotal: eur(0) },
+      viewer,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+});
 ```
 
 ### src/entities/contact.ts
@@ -529,6 +605,9 @@ export const productTable = buildEntityTable("product", productEntity);
 //             on its `lines` sub-fields (Issue #1835), plus a declarative
 //             entityEdit screen that renders the list end-to-end via
 //             EmbeddedListField, no custom-screen code required
+//   invoice-receive — actionForm whose net/VAT/gross head fields are derived
+//             from the lines (`derive`); the handler recomputes them with
+//             `withFormDerivations`, so client-sent totals are never trusted
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { contactEntity } from "./entities/contact";
@@ -536,6 +615,8 @@ import { invoiceEntity } from "./entities/invoice";
 import { productEntity } from "./entities/product";
 import { contactCreate } from "./handlers/contact-create.write";
 import { contactDetail } from "./handlers/contact-detail.query";
+import { invoiceReceive } from "./handlers/invoice-receive.write";
+import { invoiceReceiveScreen } from "./screens/invoice-receive.screen";
 
 export { contactEntity } from "./entities/contact";
 export { invoiceEntity } from "./entities/invoice";
@@ -557,6 +638,7 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
 
   r.writeHandler(contactCreate);
   r.queryHandler(contactDetail);
+  r.writeHandler(invoiceReceive);
 
   r.crud("product", productEntity, { write: adminWrite, read: openRead });
   r.crud("invoice", invoiceEntity, { write: adminWrite, read: openRead });
@@ -569,6 +651,8 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
       sections: [{ columns: 1, fields: ["customer", "lines"] }],
     },
   });
+
+  r.screen(invoiceReceiveScreen);
 });
 ```
 
@@ -646,3 +730,110 @@ export const contactDetail = defineQueryHandler({
   },
 });
 ```
+
+### src/handlers/invoice-receive.write.ts
+
+```ts
+import {
+  defineWriteHandler,
+  fieldToZod,
+  withFormDerivations,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { invoiceReceiveLines, invoiceReceiveScreen } from "../screens/invoice-receive.screen";
+
+const moneyPayload = z.object({ amount: z.number(), currency: z.string().min(1) });
+
+// The preprocess recomputes net/VAT/gross before validation: totals sent by the
+// client never reach the handler.
+const receiveInput = withFormDerivations(
+  z.object({
+    supplier: z.string().min(1),
+    invoiceNumber: z.string().min(1),
+    lines: fieldToZod(invoiceReceiveLines, ["EUR"]),
+    netTotal: moneyPayload,
+    vatRate: z.number().optional(),
+    vatTotal: moneyPayload,
+    grossTotal: moneyPayload,
+  }),
+  invoiceReceiveScreen,
+);
+
+export const invoiceReceive = defineWriteHandler({
+  name: "invoice:receive",
+  schema: receiveInput,
+  access: { roles: ["Admin"] },
+  handler: async (event) => ({
+    isSuccess: true,
+    data: {
+      netTotal: event.payload.netTotal,
+      vatTotal: event.payload.vatTotal,
+      grossTotal: event.payload.grossTotal,
+    },
+  }),
+});
+```
+
+### src/screens/invoice-receive.screen.ts
+
+```ts
+import {
+  type ActionFormScreenDefinition,
+  createDecimalField,
+  createEmbeddedListField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const euro = { kind: "literal", code: "EUR" } as const;
+
+export const invoiceReceiveLines = createEmbeddedListField(
+  {
+    description: { type: "text", required: true },
+    amount: { type: "money", required: true },
+    vatRate: { type: "decimal", scale: 2, required: true },
+    vatAmount: { type: "money" },
+  },
+  {
+    derived: { vatAmount: { op: "percent", from: ["amount", "vatRate"] } },
+    totals: ["amount", "vatAmount"],
+  },
+);
+
+// Net/VAT/gross are derived: with line items they are the sum of the lines,
+// without lines the net amount and the VAT rate are typed and VAT/gross follow.
+export const invoiceReceiveScreen: ActionFormScreenDefinition = {
+  id: "invoice-receive",
+  type: "actionForm",
+  handler: "contacts:write:invoice:receive",
+  fields: {
+    supplier: createTextField({ required: true, personal: "tenant", find: "none" }),
+    invoiceNumber: createTextField({
+      required: true,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    lines: invoiceReceiveLines,
+    netTotal: { type: "money", currency: euro },
+    vatRate: createDecimalField({ precision: 5, scale: 2 }),
+    vatTotal: { type: "money", currency: euro },
+    grossTotal: { type: "money", currency: euro },
+  },
+  derive: {
+    netTotal: { op: "listSum", list: "lines", cell: "amount" },
+    vatTotal: {
+      op: "listSum",
+      list: "lines",
+      cell: "vatAmount",
+      whenEmpty: { op: "percent", from: ["netTotal", "vatRate"] },
+    },
+    grossTotal: { op: "sum", from: ["netTotal", "vatTotal"] },
+  },
+  layout: {
+    sections: [
+      { columns: 2, fields: ["supplier", "invoiceNumber"] },
+      { columns: 1, fields: ["lines"] },
+      { columns: 2, fields: ["netTotal", "vatRate", "vatTotal", "grossTotal"] },
+    ],
+  },
+};
+```

package/agents/features.md

@@ -228,7 +228,7 @@ Requires: `file-derivatives`
 
 ## document-designer
 
-Template overview and layout editor: lists the mail, PDF and layout templates of a tenant (platform admins see the system templates and how many tenants customised each) and edits the mail layout and the PDF letterhead in the browser. Mount after template-resolver and, for the branding rail, managed-pages. Client: `documentDesignerClient()`; admin-shell lists the navs with `includeDocumentDesigner`.
+Template overview and layout editor: lists the mail, PDF and layout templates of a tenant (platform admins see the system templates and how many tenants customised each) and edits the mail layout and the PDF letterhead in the browser. Mount after template-resolver and, for the branding rail, managed-pages. Client: `documentDesignerClient()`; admin-shell lists the navs with `includeDocumentDesigner`. The tenant overview and the editors are for SystemAdmin only; the `access` option adds roles (normally `templateEditAccess(tenantEditable)` of the template-resolver mount), and the server still enforces per template which of them may save.
 
 Category: content
 
@@ -644,7 +644,7 @@ Category: data
 
 ## template-resolver
 
-Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`). Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away. Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation. How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning). A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side. `validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only. `preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10. Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.
+Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`). Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away. Editing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug: "status-update", access: { roles: ["TenantAdmin"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host's roles. Reading and delivery do not depend on it: a tenant override that exists is served. A collection mounted without `access` is SystemAdmin only. Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation. How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning). A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side. `validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only. `preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address. Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10. Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.
 
 Category: notifications
 

package/agents/widgets.md

@@ -55,6 +55,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `NavTree` |  |
 | `NumberField` | Zahlenfeld = Field + Input(kind:"number") in einem — nimmt der Screen die wiederholte id/name/value/onChange-Verdrahtung ab. |
 | `PageSection` |  |
+| `PdfPreview` |  |
 | `PercentField` |  |
 | `PhotoSlots` | Guided photo capture: one tile per requested shot in a two-column grid, each its own camera/gallery picker, filled tiles show the thumbnail. |
 | `PlainContentEditor` |  |

package/dist/db/money.d.ts

@@ -1,5 +1,6 @@
+import { toMinorUnits } from "../engine/minor-units.ts";
 import type { EntityDefinition } from "../engine/types/index.ts";
-export declare function toMinorUnits(amount: number): number;
+export { toMinorUnits };
 export declare function moneyPayloadToMinorUnits(raw: unknown): number | undefined;
 export declare function flattenMoney(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
 /** Shape of a single rehydrated money field — {amount major, currency,

package/dist/db/money.js

@@ -30,15 +30,10 @@
 // Anders als locatedTimestamp behalten wir den Field-Namen `<name>` als
 // amount-Spalte (Legacy DB-Convention für Money — `SUM(buying_price)` bleibt
 // idiomatisch). `<name>Currency` ist die zusätzliche Spalte.
+import { MINOR_UNIT_SCALE, toMinorUnits } from "../engine/minor-units.js";
 import { DEFAULT_CURRENCIES } from "../engine/types/index.js";
 const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
-// 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.
-const MINOR_UNIT_SCALE = 100;
-export function toMinorUnits(amount) {
-    return Math.round(amount * MINOR_UNIT_SCALE);
-}
+export { toMinorUnits };
 function toMajorUnits(amountScaled) {
     return amountScaled / MINOR_UNIT_SCALE;
 }

package/dist/db/tenant-db.js

@@ -5,6 +5,7 @@ import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
 import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
+import { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
 import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
@@ -555,6 +556,9 @@ function buildTenantDb(options) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunCountWhere(db, table, filter));
         },
+        advisoryXactLock(namespace, key) {
+            return acquireNamespacedAdvisoryLock(db, namespace, `${tenantId}:${key}`);
+        },
         aggregate(table, spec, where) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunAggregateWhere(db, table, spec, filter));

package/dist/engine/boot-validator/entity-handler.js

@@ -642,6 +642,9 @@ function validateEmbeddedDerivedCells(fieldName, entityName, field) {
         if (!(derivedName in field.schema)) {
             throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" that is not a sub-field in its schema. Add the sub-field to the schema or remove the derived cell.`);
         }
+        if (derivedDef.op === "percent" && derivedDef.from.length !== 2) {
+            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" with op "percent", which needs exactly two sources (base, rate).`);
+        }
         for (const sourceName of derivedDef.from) {
             if (!(sourceName in field.schema)) {
                 throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading unknown sub-field "${sourceName}". Read only sub-fields that exist in the schema.`);

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

@@ -0,0 +1,4 @@
+import type { FeatureDefinition } from "../types/feature.ts";
+import type { ActionFormScreenDefinition } from "../types/screen.ts";
+export declare function validateFormDerivations(featureName: string, screenId: string, screen: ActionFormScreenDefinition): void;
+export declare function validateFormDerivationsEnforced(featureName: string, screenId: string, screen: ActionFormScreenDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/form-derivations.js

@@ -0,0 +1,82 @@
+import { orderFormDerivations } from "../form-derivations.js";
+import { parseQn } from "../qualified-name.js";
+import { formDerivationsOfSchema } from "../with-form-derivations.js";
+const NUMERIC_FORM_FIELD_TYPES = ["money", "number", "decimal"];
+const NUMERIC_SUB_FIELD_TYPES = ["money", "number", "decimal"];
+function validateFromList({ prefix, screen, target }, derivation) {
+    if (derivation.op === "percent" && derivation.from.length !== 2) {
+        throw new Error(`${prefix}.${target}: "percent" needs exactly two sources (base, rate).`);
+    }
+    for (const source of derivation.from) {
+        if (!(source in screen.fields)) {
+            throw new Error(`${prefix}.${target}: unknown source field "${source}". Name a field of this screen.`);
+        }
+    }
+}
+function validateListSum(check, derivation) {
+    const { prefix, screen, target } = check;
+    const listField = screen.fields[derivation.list];
+    if (listField === undefined) {
+        throw new Error(`${prefix}.${target}: unknown list field "${derivation.list}".`);
+    }
+    if (listField.type !== "embedded" || listField.multiple !== true) {
+        throw new Error(`${prefix}.${target}: "${derivation.list}" must be an embedded list field (multiple: true).`);
+    }
+    const cellType = listField.schema[derivation.cell]?.type;
+    if (cellType === undefined || !NUMERIC_SUB_FIELD_TYPES.includes(cellType)) {
+        throw new Error(`${prefix}.${target}: "${derivation.cell}" must be a money, number or decimal sub-field of "${derivation.list}".`);
+    }
+    const { whenEmpty } = derivation;
+    // skip: whenEmpty is optional
+    if (whenEmpty === undefined)
+        return;
+    // Type forbids a nested listSum; JS/cast callers can still pass one.
+    if (!("from" in whenEmpty)) {
+        throw new Error(`${prefix}.${target}: whenEmpty must not be a listSum.`);
+    }
+    validateFromList(check, whenEmpty);
+}
+// actionForm `derive`: every name must resolve, targets must be numeric, a
+// listSum must point at a numeric cell of an embedded list, no cycles.
+export function validateFormDerivations(featureName, screenId, screen) {
+    const derive = screen.derive;
+    // skip: the screen derives nothing
+    if (derive === undefined)
+        return;
+    const prefix = `[Feature ${featureName}] Screen "${screenId}" (actionForm) derive`;
+    for (const [target, derivation] of Object.entries(derive)) {
+        const targetField = screen.fields[target];
+        if (targetField === undefined) {
+            throw new Error(`${prefix}: key "${target}" is not a field of this screen.`);
+        }
+        if (!NUMERIC_FORM_FIELD_TYPES.includes(targetField.type)) {
+            throw new Error(`${prefix}.${target}: a derived field must be money, number or decimal, not "${targetField.type}".`);
+        }
+        const check = { prefix, screen, target };
+        if (derivation.op === "listSum")
+            validateListSum(check, derivation);
+        else
+            validateFromList(check, derivation);
+    }
+    try {
+        orderFormDerivations(derive);
+    }
+    catch (error) {
+        throw new Error(`${prefix}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+// Secure by default: a derive the handler schema doesn't recompute would let a
+// client send its own totals, so the handler must wrap with this very screen.
+export function validateFormDerivationsEnforced(featureName, screenId, screen, featureMap) {
+    // skip: the screen derives nothing
+    if (screen.derive === undefined)
+        return;
+    const { scope, name } = parseQn(screen.handler);
+    const schema = featureMap.get(scope)?.writeHandlers[name]?.schema;
+    // skip: wrapped with this screen
+    if (formDerivationsOfSchema(schema) === screen.derive)
+        return;
+    throw new Error(`[Feature ${featureName}] Screen "${screenId}" (actionForm) declares derive, but handler ` +
+        `"${screen.handler}" does not recompute it on the server. Wrap the handler schema: ` +
+        `withFormDerivations(schema, screen) with this screen object.`);
+}

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;
@@ -945,6 +946,10 @@ 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);
+    }
     validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
 // SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
@@ -1287,17 +1292,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);
                     }

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/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/template-variables.d.ts

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import type { Registry, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariables } from "./types/index.ts";
+import type { Registry, TemplateImagesVariableDef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariables } from "./types/index.ts";
 type CommonOptions = {
     readonly label?: string;
     readonly required?: boolean;
@@ -26,6 +26,7 @@ export declare const templateVariable: {
     readonly percent: (opts?: CommonOptions & {
         readonly example?: number;
     }) => TemplateScalarVariableDef;
+    readonly images: (opts?: CommonOptions) => TemplateImagesVariableDef;
     readonly list: (item: Readonly<Record<string, TemplateScalarVariableDef>>, opts?: CommonOptions & {
         readonly example?: readonly Readonly<Record<string, unknown>>[];
     }) => TemplateListVariableDef;

package/dist/engine/template-variables.js

@@ -17,6 +17,7 @@ export const templateVariable = {
         ...opts,
     }),
     percent: (opts = {}) => ({ type: "percent", ...opts }),
+    images: (opts = {}) => ({ type: "images", ...opts }),
     list: (item, opts = {}) => ({ type: "list", item, ...opts }),
 };
 const LINK_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
@@ -53,7 +54,10 @@ function scalarToZod(def) {
             return z.number().finite();
     }
 }
+const imagesSchema = z.union([z.string(), z.array(z.string())]);
 function variableToZod(def) {
+    if (def.type === "images")
+        return imagesSchema;
     if (def.type !== "list")
         return scalarToZod(def);
     return z.array(z.object(Object.fromEntries(Object.entries(def.item).map(([name, item]) => [name, withOptionality(item)]))));

package/dist/engine/types/index.d.ts

@@ -1,5 +1,5 @@
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, MaxPerTenantOptions, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
+export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, MaxPerTenantOptions, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TemplateImagesVariableDef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "@cosmicdrift/kumiko-types/define-handler";
 export type { EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "@cosmicdrift/kumiko-types/entity-handlers";
 export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, } from "@cosmicdrift/kumiko-types/event-type-map";
@@ -17,7 +17,7 @@ export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@c
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
 export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionRowIdOf, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
 export type { BelongsToRelation, EntityRelations, HasManyRelation, ManyToManyRelation, RelationDefinition, } from "@cosmicdrift/kumiko-types/relations";
-export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
+export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormFieldDerivation, FormWidth, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type { Subscribe, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, } from "@cosmicdrift/kumiko-types/tree-node";

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

@@ -0,0 +1,9 @@
+import * as z from "zod";
+import { type FormDerivationScreen } from "./form-derivations.ts";
+import type { FormFieldDerivation } from "./types/screen.ts";
+/** The `derive` a schema was wrapped with via `withFormDerivations`, so the
+ *  boot validator can prove an actionForm's handler recomputes its totals. */
+export declare function formDerivationsOfSchema(schema: unknown): Readonly<Record<string, FormFieldDerivation>> | undefined;
+/** Server counterpart of an actionForm's `derive`: recomputes the derived head
+ *  fields before the schema validates them, so client-sent totals never count. */
+export declare function withFormDerivations<Schema extends z.ZodType>(schema: Schema, screen: FormDerivationScreen): z.ZodPreprocess<Schema, unknown>;

package/dist/engine/with-form-derivations.js

@@ -0,0 +1,16 @@
+import * as z from "zod";
+import { applyFormDerivations } from "./form-derivations.js";
+const derivationsBySchema = new WeakMap();
+/** The `derive` a schema was wrapped with via `withFormDerivations`, so the
+ *  boot validator can prove an actionForm's handler recomputes its totals. */
+export function formDerivationsOfSchema(schema) {
+    return schema instanceof z.ZodType ? derivationsBySchema.get(schema) : undefined;
+}
+/** Server counterpart of an actionForm's `derive`: recomputes the derived head
+ *  fields before the schema validates them, so client-sent totals never count. */
+export function withFormDerivations(schema, screen) {
+    const wrapped = z.preprocess((value) => applyFormDerivations(value, screen), schema);
+    if (screen.derive !== undefined)
+        derivationsBySchema.set(wrapped, screen.derive);
+    return wrapped;
+}

package/dist/i18n/settings-hub-keys.js

@@ -19,6 +19,7 @@ export const SETTINGS_HUB_I18N = {
         en: "Choose a provider. Its settings appear below and are saved together with it.",
     },
     "config.settings.provider": { en: "Provider" },
+    "config.settings.provider.platformDefault": { en: "Platform default" },
     "config.settings.audience.system": {
         en: "Applies to every tenant unless a tenant sets its own value.",
     },

package/dist/search/configure-tenant-index.d.ts

@@ -0,0 +1,4 @@
+import type { Registry, TenantId } from "../engine/types/index.ts";
+import type { SearchAdapter } from "./types.ts";
+export declare function collectSearchableFieldNames(registry: Registry): readonly string[];
+export declare function configureTenantSearchIndex(searchAdapter: SearchAdapter, registry: Registry, tenantId: TenantId): Promise<void>;

package/dist/search/configure-tenant-index.js

@@ -0,0 +1,8 @@
+import { deriveSearchAdapterConfig } from "./derive-search-adapter-config.js";
+export function collectSearchableFieldNames(registry) {
+    return deriveSearchAdapterConfig(registry)?.searchableFields ?? [];
+}
+export async function configureTenantSearchIndex(searchAdapter, registry, tenantId) {
+    const fields = collectSearchableFieldNames(registry);
+    await searchAdapter.configure(tenantId, { searchableFields: fields, rankingFields: fields });
+}

package/dist/search/index.d.ts

@@ -1,3 +1,4 @@
+export { collectSearchableFieldNames, configureTenantSearchIndex, } from "./configure-tenant-index.ts";
 export { deriveSearchAdapterConfig } from "./derive-search-adapter-config.ts";
 export { createInMemorySearchAdapter } from "./in-memory-adapter.ts";
 export { purgeSearchDocumentsForSubject } from "./purge-subject.ts";

package/dist/search/index.js

@@ -2,6 +2,7 @@
 // Damit lädt der Main-Barrel keinen Meilisearch-Client beim bloßen Anfassen
 // von SearchAdapter-Types. Apps die Meilisearch nicht nutzen, ziehen den
 // Client-Code nicht mit rein.
+export { collectSearchableFieldNames, configureTenantSearchIndex, } from "./configure-tenant-index.js";
 export { deriveSearchAdapterConfig } from "./derive-search-adapter-config.js";
 export { createInMemorySearchAdapter } from "./in-memory-adapter.js";
 export { purgeSearchDocumentsForSubject } from "./purge-subject.js";

package/dist/ui-types/index.d.ts

@@ -1,6 +1,8 @@
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export type { DerivedCellRoundingTarget } from "../engine/embedded-derived.ts";
 export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.ts";
+export type { FormDerivationScreen } from "../engine/form-derivations.ts";
+export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperand, } from "../engine/form-derivations.ts";
 export type { ParsedRefTarget } from "../engine/parse-ref-target.ts";
 export { parseRefTarget } from "../engine/parse-ref-target.ts";
 export type { FieldsOrGroupsSection, UnavailableSelectOption } from "../engine/screen-helpers.ts";

package/dist/ui-types/index.js

@@ -21,6 +21,7 @@
 // helper with no cross-module side-effects.
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.js";
+export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperand, } from "../engine/form-derivations.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.377.0",
+  "version": "0.378.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -199,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.377.0",
+    "@cosmicdrift/kumiko-types": "0.378.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.377.0",
+    "@cosmicdrift/kumiko-testing": "0.378.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,36 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "actionForm can derive head totals from an embedded list",
+    "detail": "An actionForm screen declares `derive` for head fields: sum, subtract, multiply, percent over other fields, or listSum over one cell of an embedded list with an optional whenEmpty fallback. The renderer recomputes them live and shows them read-only; a listSum without whenEmpty becomes an input while the list is empty. withFormDerivations(schema, screen) recomputes them on the server before validation, so client totals are never trusted; boot fails when the handler schema is not wrapped with the screen's own derive. A field that only feeds a `whenEmpty` fallback is read-only while the lists have rows. New embedded derived op `percent` (from[0] * from[1] / 100).",
+    "migration": "Add `derive` to the actionForm screen and wrap the handler schema with `withFormDerivations(schema, screen)`; new embedded derived op `percent`."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Extension-selector settings form is one standard configEdit screen",
+    "detail": "Without owner panels the provider form is the `<owner>-tenant` screen itself (no dashboard, no `<owner>-tenant-selection`). The provider select offers an empty \"platform default\" option next to the plugin ids."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Search index setup helpers",
+    "detail": "collectSearchableFieldNames(registry) returns the deduplicated searchable fields of all entities and configureTenantSearchIndex(adapter, registry, tenantId) configures a tenant index with them, both exported from the search entry."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "TenantDb.advisoryXactLock",
+    "detail": "ctx.db.advisoryXactLock(namespace, key) takes a transaction-scoped pg_advisory_xact_lock keyed on the handle's own tenantId plus key, so tenants never contend and the caller cannot pick another tenant. It needs no unsafeRaw grant."
+  },
+  {
+    "version": "0.378.0",
+    "type": "breaking",
+    "title": "Boot check for projectionList writeHandler actions",
+    "detail": "Boot now rejects projectionList rowActions and toolbarActions of kind writeHandler whose handler is not a registered write-handler QN. Such actions only failed on click before.",
+    "migration": "Fix the handler QN to \"<feature>:write:<short>\" of a handler declared via r.writeHandler(...), or remove the action. Apps that fail to boot name the screen and action id in the error."
+  },
   {
     "version": "0.377.0",
     "type": "improvement",