@cosmicdrift/kumiko-framework 0.186.3 → 0.187.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.186.3",
+  "version": "0.187.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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.186.3",
+    "@cosmicdrift/kumiko-types": "0.187.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.186.3",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.187.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -819,6 +819,146 @@ describe("embedded-list derived cell recomputation (kumiko-framework#1837)", ()
       expect(result.data["lines"]).toEqual([{ qty: 3, amount: 999 }]);
     }
   });
+
+  // --- kumiko-framework#1852: a fractional product on a money/decimal
+  // target isn't representable by the target sub-field's strict
+  // integer/scale validation — round to the target's declared precision
+  // before it's written back, instead of rejecting the whole row. ---
+
+  test("a fractional product on a money target is rounded to whole minor units (kaufmännisch)", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField(
+          {
+            qty: { type: "decimal", scale: 2, required: true },
+            price: { type: "money", required: true },
+            amount: { type: "money", required: false },
+          },
+          { derived: { amount: { op: "multiply", from: ["qty", "price"] } } },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    // 12.34 * 187 = 2307.58 minor units — not representable by money's
+    // integer constraint. Rounds up (half-away-from-zero would round .58
+    // to .0 anyway, this just isn't a half-step case).
+    const result = schema.safeParse({ lines: [{ qty: 12.34, price: 187 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const row = (result.data["lines"] as readonly Record<string, unknown>[])[0];
+      expect(row?.["amount"]).toBe(2308);
+    }
+  });
+
+  test("a negative product exactly on a half-step rounds away from zero, not toward it", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField(
+          {
+            qty: { type: "decimal", scale: 1, required: true },
+            price: { type: "money", required: true },
+            amount: { type: "money", required: false },
+          },
+          { derived: { amount: { op: "multiply", from: ["qty", "price"] } } },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    // 2.5 * -923 = -2307.5 exactly. `Math.round(-2307.5)` alone would give
+    // -2307 (rounds toward zero for negative .5); half-away-from-zero must
+    // give -2308.
+    const result = schema.safeParse({ lines: [{ qty: 2.5, price: -923 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const row = (result.data["lines"] as readonly Record<string, unknown>[])[0];
+      expect(row?.["amount"]).toBe(-2308);
+    }
+  });
+
+  test("a decimal target rounds correctly through the classic float half-step trap", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField(
+          {
+            qty: { type: "decimal", scale: 3, required: true },
+            price: { type: "number", required: true },
+            amount: { type: "decimal", scale: 2, required: false },
+          },
+          { derived: { amount: { op: "multiply", from: ["qty", "price"] } } },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    // 1.005 * 1 === 1.005 as a JS number, but 1.005 * 100 is actually
+    // 100.49999999999999 in float — naive Math.round would floor this to
+    // 1.00 instead of the mathematically-correct 1.01.
+    const result = schema.safeParse({ lines: [{ qty: 1.005, price: 1 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const row = (result.data["lines"] as readonly Record<string, unknown>[])[0];
+      expect(row?.["amount"]).toBe(1.01);
+    }
+  });
+
+  test("totalsMatch validates against the rounded derived values, not the raw fractional products", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        total: createMoneyField({ required: true }),
+        lines: createEmbeddedListField(
+          {
+            qty: { type: "decimal", scale: 1, required: true },
+            price: { type: "money", required: true },
+            amount: { type: "money", required: false },
+          },
+          {
+            derived: { amount: { op: "multiply", from: ["qty", "price"] } },
+            totalsMatch: { amount: "total" },
+          },
+        ),
+      },
+      defaultCurrency: "EUR",
+    });
+    const schema = buildInsertSchema(entity);
+    // Each row's raw product is x.5 and rounds up by 1 minor unit: row 1 =
+    // 2.5 * 923 = 2307.5 -> 2308; row 2 = 3.5 * 100 = 350.0 -> 350 exactly.
+    // Sibling total must equal the sum of the ROUNDED amounts (26.58 EUR),
+    // not the sum of the raw fractional products.
+    const result = schema.safeParse({
+      total: { amount: 26.58, currency: "EUR" },
+      lines: [
+        { qty: 2.5, price: 923 },
+        { qty: 3.5, price: 100 },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("a number-typed derived cell is left unrounded (unit-agnostic pass-through)", () => {
+    const entity = 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"] } } },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const result = schema.safeParse({ lines: [{ qty: 1.5, price: 2 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const row = (result.data["lines"] as readonly Record<string, unknown>[])[0];
+      expect(row?.["amount"]).toBe(3);
+    }
+  });
 });
 
 // --- Update schema (all partial) ---

package/src/engine/embedded-derived.ts

@@ -1,11 +1,13 @@
-import type { EmbeddedDerivedCellDef } from "./types";
+import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } 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). */
+ *  it's given (caller passes minor units for money, not major/float).
+ *  `withDerivedCells` rounds the result to the target sub-field's declared
+ *  precision afterward. */
 export function computeDerivedCellValue(
   op: EmbeddedDerivedCellDef["op"],
   values: readonly (number | undefined)[],
@@ -21,16 +23,46 @@ export function computeDerivedCellValue(
   return rest.reduce((remainder, value) => remainder - value, first ?? 0);
 }
 
+export type DerivedCellRoundingTarget = {
+  readonly type: EmbeddedSubFieldDef["type"];
+  readonly scale?: number;
+};
+
+/** Rounds a derived cell's computed value to the precision its target
+ *  sub-field declares — commercial rounding (round-half-away-from-zero,
+ *  correct for signed minor-unit money). money → integer; decimal → `scale`
+ *  digits; every other target type passes through unchanged (the function
+ *  stays unit-agnostic for those). */
+export function roundDerivedCellValue(value: number, target: DerivedCellRoundingTarget): number {
+  if (target.type === "money") return roundHalfAwayFromZero(value, 0);
+  if (target.type === "decimal") return roundHalfAwayFromZero(value, target.scale ?? 0);
+  return value;
+}
+
+function roundHalfAwayFromZero(value: number, decimals: number): number {
+  const factor = 10 ** decimals;
+  // `toPrecision` strips the float-multiplication noise (e.g. 1.005 * 100
+  // === 100.49999999999999) before rounding, so a value that's
+  // mathematically exactly at the half-step doesn't fall to the wrong side.
+  // ponytail: toPrecision(15) can shift by ±1 minor unit for values near Number.MAX_SAFE_INTEGER (2^53); fine for realistic money amounts.
+  const scaled = Number((Math.abs(value) * factor).toPrecision(15));
+  return (Math.sign(value) * Math.round(scaled)) / factor;
+}
+
 /** 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. */
+ *  untouched — validation downstream rejects it. The computed value is
+ *  rounded to the target sub-field's declared precision (`schema`) before
+ *  it's written back, so a fractional product lands on a value the target
+ *  type can actually represent. */
 export function withDerivedCells(
   row: unknown,
   derived: Readonly<Record<string, EmbeddedDerivedCellDef>>,
+  schema: Readonly<Record<string, EmbeddedSubFieldDef>>,
 ): unknown {
   if (typeof row !== "object" || row === null || Array.isArray(row)) return row;
   const source = row as Readonly<Record<string, unknown>>;
@@ -44,7 +76,8 @@ export function withDerivedCells(
     if (computed === undefined) {
       delete copy[cellName];
     } else {
-      copy[cellName] = computed;
+      const target = schema[cellName];
+      copy[cellName] = target === undefined ? computed : roundDerivedCellValue(computed, target);
     }
   }
   return copy;

package/src/engine/schema-builder.ts

@@ -212,7 +212,7 @@ export function fieldToZod(
       const row =
         derived === undefined
           ? baseRow
-          : z.preprocess((value) => withDerivedCells(value, derived), baseRow);
+          : z.preprocess((value) => withDerivedCells(value, derived, field.schema), baseRow);
       if (field.multiple !== true) return row;
       // `required: true` means non-empty, same reading as multiSelect —
       // whether the key may be omitted at all is decided by buildInsertSchema
@@ -299,6 +299,10 @@ export function fieldToZod(
 // sum in the entity's default currency against a sibling amount tagged with
 // a different currency string still passes. Add a currency-equality check
 // here if multi-currency siblings become a real case.
+//
+// Known limitation: compares against rounded `derived` cells, i.e.
+// "sum-of-rounded" not "round-of-sum" (kumiko-framework#1866). Follow-up
+// for a computed, read-only sibling total: kumiko-framework#1873.
 function applyTotalsMatchRefinements(
   entity: EntityDefinition,
   schema: z.ZodObject<Record<string, z.ZodTypeAny>>,

package/src/ui-types/index.ts

@@ -20,7 +20,8 @@
 // When adding a symbol here, verify it's either a type or a pure
 // helper with no cross-module side-effects.
 
-export { computeDerivedCellValue } from "../engine/embedded-derived";
+export type { DerivedCellRoundingTarget } from "../engine/embedded-derived";
+export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived";
 export type { ParsedRefTarget } from "../engine/parse-ref-target";
 export { parseRefTarget } from "../engine/parse-ref-target";
 export {