@cosmicdrift/kumiko-framework 0.183.2 → 0.185.0

package/src/engine/__tests__/schema-builder.test.ts

@@ -433,6 +433,63 @@ describe("buildInsertSchema", () => {
     expect(required.safeParse({ lines: [{ accountId: "bank" }] }).success).toBe(true);
   });
 
+  test("select sub-field accepts a listed option, rejects an unlisted string", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        lines: createEmbeddedListField({
+          status: { type: "select", options: ["draft", "sent"], required: true },
+        }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ lines: [{ status: "sent" }] }).success).toBe(true);
+    expect(schema.safeParse({ lines: [{ status: "archived" }] }).success).toBe(false);
+  });
+
+  test("reference sub-field accepts a UUID, rejects a non-UUID string", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        lines: createEmbeddedListField({
+          productId: { type: "reference", entity: "product", required: true },
+        }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(
+      schema.safeParse({ lines: [{ productId: "550e8400-e29b-41d4-a716-446655440000" }] }).success,
+    ).toBe(true);
+    expect(schema.safeParse({ lines: [{ productId: "not-a-uuid" }] }).success).toBe(false);
+  });
+
+  test("minItems/maxItems bound an embedded list", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        lines: createEmbeddedListField(
+          { accountId: { type: "text", required: true } },
+          { minItems: 2, maxItems: 3 },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ lines: [{ accountId: "a" }] }).success).toBe(false);
+    expect(schema.safeParse({ lines: [{ accountId: "a" }, { accountId: "b" }] }).success).toBe(
+      true,
+    );
+    expect(
+      schema.safeParse({
+        lines: [{ accountId: "a" }, { accountId: "b" }, { accountId: "c" }],
+      }).success,
+    ).toBe(true);
+    expect(
+      schema.safeParse({
+        lines: [{ accountId: "a" }, { accountId: "b" }, { accountId: "c" }, { accountId: "d" }],
+      }).success,
+    ).toBe(false);
+  });
+
   test("money sub-field accepts signed integer minor units, rejects fractions", () => {
     const entity = createEntity({
       table: "Test",
@@ -603,6 +660,167 @@ describe("buildInsertSchema", () => {
   });
 });
 
+// --- fw#1839: embedded-list timestamp sub-field ---
+
+describe("embedded sub-field: timestamp", () => {
+  test("accepts a valid ISO datetime, rejects an invalid string", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        lines: createEmbeddedListField({
+          loggedAt: { type: "timestamp", required: true },
+        }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ lines: [{ loggedAt: "2026-08-06T10:00:00Z" }] }).success).toBe(true);
+    expect(schema.safeParse({ lines: [{ loggedAt: "not-a-date" }] }).success).toBe(false);
+    expect(schema.safeParse({ lines: [{ loggedAt: "2026-08-06" }] }).success).toBe(false);
+  });
+});
+
+// --- fw#1839: totalsMatch cross-field validation (schema-level, shared by
+// client form-controller and server write handler via the same
+// z.object().safeParse() call) ---
+
+describe("totalsMatch (fw#1839)", () => {
+  function invoiceEntity() {
+    return createEntity({
+      table: "Invoices",
+      fields: {
+        total: createMoneyField({ required: true }),
+        lines: createEmbeddedListField(
+          { amount: { type: "money", required: true } },
+          { totalsMatch: { amount: "total" } },
+        ),
+      },
+      defaultCurrency: "EUR",
+    });
+  }
+
+  test("accepts when the sum of line amounts (minor units) equals the sibling total (major units)", () => {
+    const schema = buildInsertSchema(invoiceEntity());
+    const result = schema.safeParse({
+      total: { amount: 30, currency: "EUR" },
+      lines: [{ amount: 1000 }, { amount: 2000 }],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects when the sum diverges from the sibling total, issue path is the embedded field name", () => {
+    const schema = buildInsertSchema(invoiceEntity());
+    const result = schema.safeParse({
+      total: { amount: 30, currency: "EUR" },
+      lines: [{ amount: 1000 }, { amount: 1500 }],
+    });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues.some((issue) => issue.path.join(".") === "lines")).toBe(true);
+    }
+  });
+
+  test("update payload omitting the embedded list is not checked (nothing to sum)", () => {
+    const schema = buildUpdateSchema(invoiceEntity());
+    expect(schema.safeParse({ total: { amount: 30, currency: "EUR" } }).success).toBe(true);
+  });
+
+  test("update payload omitting the sibling total is not checked (nothing to compare against)", () => {
+    const schema = buildUpdateSchema(invoiceEntity());
+    expect(schema.safeParse({ lines: [{ amount: 1000 }, { amount: 1500 }] }).success).toBe(true);
+  });
+});
+
+// --- kumiko-framework#1837: derived-cell server-side recomputation — the
+// server is the authority for derived cells, a client value is overwritten
+// with the recomputed one instead of merely checked against it. ---
+
+describe("embedded-list derived cell recomputation (kumiko-framework#1837)", () => {
+  function orderEntity() {
+    return createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField(
+          {
+            qty: { type: "number", required: true },
+            price: { type: "number", required: true },
+            amount: { type: "number", required: false },
+          },
+          { derived: { amount: { op: "multiply", from: ["qty", "price"] } } },
+        ),
+      },
+    });
+  }
+
+  test("a matching client-sent derived cell parses through unchanged", () => {
+    const schema = buildInsertSchema(orderEntity());
+    const result = schema.safeParse({ lines: [{ qty: 3, price: 10, amount: 30 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["lines"]).toEqual([{ qty: 3, price: 10, amount: 30 }]);
+    }
+  });
+
+  test("a diverging client-sent derived cell is overwritten with the server-computed value, not rejected", () => {
+    const schema = buildInsertSchema(orderEntity());
+    const result = schema.safeParse({ lines: [{ qty: 3, price: 10, amount: 99 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["lines"]).toEqual([{ qty: 3, price: 10, amount: 30 }]);
+    }
+  });
+
+  test("a derived cell omitted from the payload is filled in server-side", () => {
+    const schema = buildInsertSchema(orderEntity());
+    const result = schema.safeParse({ lines: [{ qty: 3, price: 10 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["lines"]).toEqual([{ qty: 3, price: 10, amount: 30 }]);
+    }
+  });
+
+  test("a missing source for a multiply-derived cell leaves the cell unset rather than 0", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField(
+          {
+            qty: { type: "number", required: true },
+            price: { type: "number", required: false },
+            amount: { type: "number", required: false },
+          },
+          { derived: { amount: { op: "multiply", from: ["qty", "price"] } } },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const result = schema.safeParse({ lines: [{ qty: 3, amount: 30 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const row = (result.data["lines"] as readonly Record<string, unknown>[])[0];
+      expect(row).toBeDefined();
+      expect(Object.hasOwn(row as Record<string, unknown>, "amount")).toBe(false);
+    }
+  });
+
+  test("an embedded-list field without `derived` leaves a client-sent value untouched", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField({
+          qty: { type: "number", required: true },
+          amount: { type: "number", required: false },
+        }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const result = schema.safeParse({ lines: [{ qty: 3, amount: 999 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["lines"]).toEqual([{ qty: 3, amount: 999 }]);
+    }
+  });
+});
+
 // --- Update schema (all partial) ---
 
 describe("buildUpdateSchema", () => {

package/src/engine/boot-validator/entity-handler.ts

@@ -1,5 +1,5 @@
 import { parseRefTarget } from "../parse-ref-target";
-import type { FeatureDefinition } from "../types";
+import type { EmbeddedFieldDef, EntityDefinition, FeatureDefinition } from "../types";
 
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
 
@@ -364,7 +364,19 @@ export function validateFileFields(feature: FeatureDefinition): boolean {
 
 // --- Embedded field validation ---
 
-const VALID_EMBEDDED_SUB_TYPES = new Set(["text", "number", "boolean", "date", "money", "decimal"]);
+const VALID_EMBEDDED_SUB_TYPES = new Set([
+  "text",
+  "number",
+  "boolean",
+  "date",
+  "money",
+  "decimal",
+  "select",
+  "reference",
+  "timestamp",
+]);
+
+const NUMERIC_EMBEDDED_SUB_TYPES = new Set(["number", "money", "decimal"]);
 
 // 15 is where 10^scale exhausts a double's integer range — beyond it the
 // scale check in the write schema could no longer hold.
@@ -372,15 +384,83 @@ function isValidEmbeddedDecimalScale(scale: number): boolean {
   return Number.isInteger(scale) && scale >= 0 && scale <= 15;
 }
 
-// Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef-Validation.
-//   1) referenced entity existiert (same-feature OR cross-feature
-//      qualifiziert per "<feature>:<entity>"). Same-feature ist
-//      Default; cross-feature verlangt expliziten ":"-Prefix.
-//   2) labelField (wenn gesetzt) existiert auf der referenced Entity.
-//   3) Self-Reference erlaubt (entity → entity).
-//   4) Audit-Fix: Query-Handler `<feature>:query:<entity>:list` muss
-//      registriert sein — der Renderer feuert den beim Combobox-
-//      Open. Ohne Handler crasht die Combobox zur Laufzeit.
+// Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef validation, shared by
+// top-level reference fields and reference sub-fields of an embedded field
+// (only the field-path in error messages differs, e.g. "accountId" vs
+// "lines.accountId", so a failure is locatable either way).
+//   1) referenced entity exists (same-feature OR cross-feature qualified via
+//      "<feature>:<entity>"). Same-feature is the default; cross-feature
+//      requires an explicit ":" prefix.
+//   2) labelField (if set) exists on the referenced entity.
+//   3) Query handler `<feature>:query:<entity>:list` is registered — the
+//      renderer fires it on Combobox open, so a missing handler crashes the
+//      Combobox at runtime.
+function validateReferenceTarget(
+  entityName: string,
+  fieldPath: string,
+  refString: string,
+  labelField: string | undefined,
+  feature: FeatureDefinition,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  const target = parseRefTarget(refString, feature.name);
+  const targetFeature = featureMap.get(target.featureName);
+  if (!targetFeature) {
+    const knownFeatures = [...featureMap.keys()].sort().join(", ");
+    throw new Error(
+      `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+        `targets unknown feature "${target.featureName}" via "${refString}". ` +
+        `Known features: ${knownFeatures}.`,
+    );
+  }
+  const targetEntity = targetFeature.entities?.[target.entityName];
+  if (!targetEntity) {
+    const known =
+      Object.keys(targetFeature.entities ?? {})
+        .sort()
+        .join(", ") || "(none)";
+    const where =
+      target.featureName === feature.name
+        ? `in this feature`
+        : `in feature "${target.featureName}"`;
+    throw new Error(
+      `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+        `targets unknown entity "${target.entityName}" ${where}. ` +
+        `Known entities: ${known}.`,
+    );
+  }
+  if (labelField !== undefined) {
+    const knownFields = Object.keys(targetEntity.fields);
+    // "id" always exists, even without an explicit field definition (PK).
+    if (labelField !== "id" && !knownFields.includes(labelField)) {
+      throw new Error(
+        `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+          `references labelField "${labelField}" which does not exist on entity ` +
+          `"${target.entityName}". Known fields: ${[...knownFields, "id"].sort().join(", ")}.`,
+      );
+    }
+  }
+  // Pins query-handler existence. The renderer fires
+  // `<targetFeature>:query:<targetEntity>:list` on Combobox open
+  // (use-reference-lookup, ReferenceInput); without a handler that's a 404
+  // on first click. defaultEntityQueryHandler names are stored short as
+  // "<entity>:list" in feature.queryHandlers.
+  const expectedHandlerShortName = `${target.entityName}:list`;
+  if (targetFeature.queryHandlers[expectedHandlerShortName] === undefined) {
+    throw new Error(
+      `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+        `targets entity "${target.entityName}" but no list-query-handler is registered ` +
+        `there. Add r.queryHandler(defineEntityListHandler("${target.entityName}", ` +
+        `${target.entityName}Entity)) to feature "${target.featureName}", or pick a ` +
+        `different label/entity.`,
+    );
+  }
+}
+
+// Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef validation for top-level
+// reference fields (self-reference, entity → entity, is allowed). The actual
+// checks run in validateReferenceTarget — shared with the reference
+// sub-fields of an embedded field (validateEmbeddedFields).
 export function validateReferenceFields(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -388,64 +468,22 @@ export function validateReferenceFields(
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type !== "reference") continue;
-
-      const target = parseRefTarget(field.entity, feature.name);
-      const targetFeature = featureMap.get(target.featureName);
-      if (!targetFeature) {
-        const knownFeatures = [...featureMap.keys()].sort().join(", ");
-        throw new Error(
-          `[Feature ${feature.name}] Reference field "${fieldName}" on entity "${entityName}" ` +
-            `targets unknown feature "${target.featureName}" via "${field.entity}". ` +
-            `Known features: ${knownFeatures}.`,
-        );
-      }
-      const targetEntity = targetFeature.entities?.[target.entityName];
-      if (!targetEntity) {
-        const known =
-          Object.keys(targetFeature.entities ?? {})
-            .sort()
-            .join(", ") || "(none)";
-        const where =
-          target.featureName === feature.name
-            ? `in this feature`
-            : `in feature "${target.featureName}"`;
-        throw new Error(
-          `[Feature ${feature.name}] Reference field "${fieldName}" on entity "${entityName}" ` +
-            `targets unknown entity "${target.entityName}" ${where}. ` +
-            `Known entities: ${known}.`,
-        );
-      }
-      if (field.labelField !== undefined) {
-        const knownFields = Object.keys(targetEntity.fields);
-        // "id" ist immer da, auch ohne Field-Definition (PK).
-        if (field.labelField !== "id" && !knownFields.includes(field.labelField)) {
-          throw new Error(
-            `[Feature ${feature.name}] Reference field "${fieldName}" on entity "${entityName}" ` +
-              `references labelField "${field.labelField}" which does not exist on entity ` +
-              `"${target.entityName}". Known fields: ${[...knownFields, "id"].sort().join(", ")}.`,
-          );
-        }
-      }
-      // Audit-Fix #2: Query-Handler-Existenz pinnen. Renderer feuert
-      // `<targetFeature>:query:<targetEntity>:list` beim Combobox-Open
-      // (use-reference-lookup, ReferenceInput); ohne Handler kommt
-      // beim ersten Klick ein 404. defaultEntityQueryHandler-Names
-      // sind als kurz "<entity>:list" in feature.queryHandlers gespeichert.
-      const expectedHandlerShortName = `${target.entityName}:list`;
-      if (targetFeature.queryHandlers[expectedHandlerShortName] === undefined) {
-        throw new Error(
-          `[Feature ${feature.name}] Reference field "${fieldName}" on entity "${entityName}" ` +
-            `targets entity "${target.entityName}" but no list-query-handler is registered ` +
-            `there. Add r.queryHandler(defineEntityListHandler("${target.entityName}", ` +
-            `${target.entityName}Entity)) to feature "${target.featureName}", or pick a ` +
-            `different label/entity.`,
-        );
-      }
+      validateReferenceTarget(
+        entityName,
+        fieldName,
+        field.entity,
+        field.labelField,
+        feature,
+        featureMap,
+      );
     }
   }
 }
 
-export function validateEmbeddedFields(feature: FeatureDefinition): void {
+export function validateEmbeddedFields(
+  feature: FeatureDefinition,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type !== "embedded") continue;
@@ -467,11 +505,155 @@ export function validateEmbeddedFields(feature: FeatureDefinition): void {
             `Embedded field "${fieldName}.${subName}" on entity "${entityName}" has invalid scale ${subField.scale}. Must be an integer between 0 and 15.`,
           );
         }
+        if (subField.type === "select" && subField.options.length === 0) {
+          throw new Error(
+            `Embedded field "${fieldName}.${subName}" on entity "${entityName}" has empty options`,
+          );
+        }
+        // Reference sub-fields get the same target/labelField/query-handler
+        // checks as a top-level reference field — same failure mode
+        // (crashing Combobox at runtime) if skipped, so it can't stay a
+        // second-class citizen just because it's nested.
+        if (subField.type === "reference") {
+          validateReferenceTarget(
+            entityName,
+            `${fieldName}.${subName}`,
+            subField.entity,
+            subField.labelField,
+            feature,
+            featureMap,
+          );
+        }
+      }
+
+      validateEmbeddedListMetadata(fieldName, entityName, field, entity);
+    }
+  }
+}
+
+function validateEmbeddedListBounds(
+  fieldName: string,
+  entityName: string,
+  field: EmbeddedFieldDef,
+): void {
+  if (field.minItems !== undefined && field.minItems < 0) {
+    throw new Error(
+      `Embedded-list field "${fieldName}" on entity "${entityName}" has invalid minItems ${field.minItems}. Must be >= 0.`,
+    );
+  }
+  if (field.maxItems !== undefined && field.maxItems < 1) {
+    throw new Error(
+      `Embedded-list field "${fieldName}" on entity "${entityName}" has invalid maxItems ${field.maxItems}. Must be >= 1.`,
+    );
+  }
+  if (
+    field.minItems !== undefined &&
+    field.maxItems !== undefined &&
+    field.minItems > field.maxItems
+  ) {
+    throw new Error(
+      `Embedded-list field "${fieldName}" on entity "${entityName}" has minItems ${field.minItems} greater than maxItems ${field.maxItems}.`,
+    );
+  }
+}
+
+function validateEmbeddedDerivedCells(
+  fieldName: string,
+  entityName: string,
+  field: EmbeddedFieldDef,
+): void {
+  // skip: no derived cells declared — nothing to validate
+  if (field.derived === undefined) return;
+  for (const [derivedName, derivedDef] of Object.entries(field.derived)) {
+    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.`,
+      );
+    }
+    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}".`,
+        );
       }
     }
   }
 }
 
+function validateEmbeddedTotalsColumns(
+  fieldName: string,
+  entityName: string,
+  field: EmbeddedFieldDef,
+): void {
+  // skip: no totals columns declared — nothing to validate
+  if (field.totals === undefined) return;
+  for (const totalName of field.totals) {
+    const totalSubField = field.schema[totalName];
+    if (!totalSubField || !NUMERIC_EMBEDDED_SUB_TYPES.has(totalSubField.type)) {
+      throw new Error(
+        `Embedded-list field "${fieldName}" on entity "${entityName}" lists "${totalName}" in totals, but it is not a number/money/decimal sub-field.`,
+      );
+    }
+  }
+}
+
+function validateEmbeddedTotalsMatch(
+  fieldName: string,
+  entityName: string,
+  field: EmbeddedFieldDef,
+  entity: EntityDefinition,
+): void {
+  // skip: no totalsMatch declared — nothing to validate
+  if (field.totalsMatch === undefined) return;
+  for (const [subFieldName, siblingFieldName] of Object.entries(field.totalsMatch)) {
+    const subField = field.schema[subFieldName];
+    if (subField?.type !== "money") {
+      throw new Error(
+        `Embedded-list field "${fieldName}" on entity "${entityName}" has a totalsMatch entry for "${subFieldName}", which is not a money sub-field in its schema.`,
+      );
+    }
+    const siblingField = entity.fields[siblingFieldName];
+    if (siblingField?.type !== "money") {
+      throw new Error(
+        `Embedded-list field "${fieldName}" on entity "${entityName}" has a totalsMatch entry mapping "${subFieldName}" to sibling field "${siblingFieldName}", which is not a money field on entity "${entityName}".`,
+      );
+    }
+  }
+}
+
+function validateEmbeddedDerivedAndTotals(
+  fieldName: string,
+  entityName: string,
+  field: EmbeddedFieldDef,
+  entity: EntityDefinition,
+): void {
+  validateEmbeddedDerivedCells(fieldName, entityName, field);
+  validateEmbeddedTotalsColumns(fieldName, entityName, field);
+  validateEmbeddedTotalsMatch(fieldName, entityName, field, entity);
+}
+
+function validateEmbeddedListMetadata(
+  fieldName: string,
+  entityName: string,
+  field: EmbeddedFieldDef,
+  entity: EntityDefinition,
+): void {
+  validateEmbeddedListBounds(fieldName, entityName, field);
+  if (
+    field.multiple !== true &&
+    (field.minItems !== undefined ||
+      field.maxItems !== undefined ||
+      field.derived !== undefined ||
+      field.totals !== undefined ||
+      field.totalsMatch !== undefined)
+  ) {
+    throw new Error(
+      `Embedded field "${fieldName}" on entity "${entityName}" sets minItems/maxItems/derived/totals/totalsMatch, which is only valid on an embedded LIST field (multiple: true).`,
+    );
+  }
+  validateEmbeddedDerivedAndTotals(fieldName, entityName, field, entity);
+}
+
 // --- MultiSelect field validation ---
 //
 // options muss non-empty sein (sonst wäre das Feld nicht benutzbar) und

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

@@ -166,7 +166,7 @@ export function validateBoot(
     if (validateFileFields(feature)) hasFileFields = true;
     validatePiiAndRetention(feature);
     validateApiExposureMatching(feature, allExposedApis, featureMap);
-    validateEmbeddedFields(feature);
+    validateEmbeddedFields(feature, featureMap);
     validateMultiSelectFields(feature);
     validateReferenceFields(feature, featureMap);
     validateTransitions(feature);

package/src/engine/embedded-derived.ts

@@ -0,0 +1,51 @@
+import type { EmbeddedDerivedCellDef } from "./types";
+
+/** Computes a derived cell from its source values. Missing/non-numeric
+ *  sources are treated as 0 for "sum"/"subtract"; "multiply" with any
+ *  missing source returns undefined (an incomplete product isn't a
+ *  meaningful partial value). Money cells are minor-unit integers — this
+ *  function is unit-agnostic, it just does arithmetic on whatever numbers
+ *  it's given (caller passes minor units for money, not major/float). */
+export function computeDerivedCellValue(
+  op: EmbeddedDerivedCellDef["op"],
+  values: readonly (number | undefined)[],
+): number | undefined {
+  if (op === "multiply") {
+    if (values.some((value) => value === undefined)) return undefined;
+    return (values as readonly number[]).reduce((product, value) => product * value, 1);
+  }
+  const numeric = values.map((value) => value ?? 0);
+  if (op === "sum") return numeric.reduce((sum, value) => sum + value, 0);
+  // subtract: first value minus every subsequent value.
+  const [first, ...rest] = numeric;
+  return rest.reduce((remainder, value) => remainder - value, first ?? 0);
+}
+
+/** Recomputes every derived cell of an embedded-list row from its raw
+ *  values, overwriting whatever the client sent instead of merely checking
+ *  it — the server is the authority for derived cells. Reads source values
+ *  from the original row (never from an already-recomputed derived cell),
+ *  so the iteration order of `derived` never matters. A row that isn't a
+ *  plain object (already invalid, or not this field's shape) passes through
+ *  untouched — validation downstream rejects it. */
+export function withDerivedCells(
+  row: unknown,
+  derived: Readonly<Record<string, EmbeddedDerivedCellDef>>,
+): unknown {
+  if (typeof row !== "object" || row === null || Array.isArray(row)) return row;
+  const source = row as Readonly<Record<string, unknown>>;
+  const copy: Record<string, unknown> = { ...source };
+  for (const [cellName, def] of Object.entries(derived)) {
+    const sourceValues = def.from.map((sourceField) => {
+      const value = source[sourceField];
+      return typeof value === "number" ? value : undefined;
+    });
+    const computed = computeDerivedCellValue(def.op, sourceValues);
+    if (computed === undefined) {
+      delete copy[cellName];
+    } else {
+      copy[cellName] = computed;
+    }
+  }
+  return copy;
+}