@cosmicdrift/kumiko-framework 0.193.1 → 0.195.0

package/src/engine/__tests__/boot-validator.test.ts

@@ -1487,6 +1487,146 @@ describe("boot-validator", () => {
       ];
       expect(() => validateBoot(features)).toThrow(/must match/);
     });
+
+    test("rejects size beyond the max variant edge", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({
+                  variants: { huge: { size: { width: 100000, height: 100000 } } },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/size/);
+    });
+
+    test("rejects maxEdge beyond the max variant edge", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { huge: { maxEdge: 100000 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/maxEdge/);
+    });
+
+    test("rejects a negative blur", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { thumb: { maxEdge: 200, blur: -5 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/blur/);
+    });
+
+    test("rejects a blur far beyond the renderer's supported sigma", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({
+                  variants: { thumb: { maxEdge: 200, blur: 100000 } },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/blur/);
+    });
+
+    test("accepts a valid blur", () => {
+      process.env["FILE_STORAGE_PROVIDER"] = "local";
+      try {
+        const features = [
+          defineFeature("profile", (r) => {
+            r.entity(
+              "person",
+              createEntity({
+                fields: {
+                  avatar: createImageField({ variants: { thumb: { maxEdge: 200, blur: 8 } } }),
+                },
+              }),
+            );
+          }),
+        ];
+        expect(() => validateBoot(features)).not.toThrow();
+      } finally {
+        delete process.env["FILE_STORAGE_PROVIDER"];
+      }
+    });
+
+    test("rejects a blurRegion that overflows the unit square", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({
+                  variants: {
+                    thumb: {
+                      maxEdge: 200,
+                      blurRegions: [{ x: -0.3, y: 0, width: 0.99, height: 0 }],
+                    },
+                  },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/blurRegions/);
+    });
+
+    test("accepts a valid blurRegion", () => {
+      process.env["FILE_STORAGE_PROVIDER"] = "local";
+      try {
+        const features = [
+          defineFeature("profile", (r) => {
+            r.entity(
+              "person",
+              createEntity({
+                fields: {
+                  avatar: createImageField({
+                    variants: {
+                      thumb: {
+                        maxEdge: 200,
+                        blurRegions: [{ x: 0.1, y: 0.1, width: 0.2, height: 0.2 }],
+                      },
+                    },
+                  }),
+                },
+              }),
+            );
+          }),
+        ];
+        expect(() => validateBoot(features)).not.toThrow();
+      } finally {
+        delete process.env["FILE_STORAGE_PROVIDER"];
+      }
+    });
   });
 
   // --- entityList column-renderer form-check ---

package/src/engine/__tests__/embedded-derived.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { roundDerivedCellValue } from "../embedded-derived";
+
+describe("roundDerivedCellValue — float-noise vs. genuine near-half values", () => {
+  test("money: float-multiplication noise just below a half-step still rounds up (deliberate)", () => {
+    // 1.005 * 100 === 100.49999999999999 in IEEE754 — this is the case the
+    // toPrecision(15) normalisation exists for: it must round to 101 minor
+    // units (100.5 → away-from-zero), not 100.
+    expect(roundDerivedCellValue(100.49999999999999, { type: "money" })).toBe(101);
+  });
+
+  test("money: a value within ~1e-16 of a half-step also snaps up, even though it is not float noise", () => {
+    // Pinned trade-off (see the `ponytail:` comment in embedded-derived.ts):
+    // toPrecision(15) cannot distinguish "float noise from a real
+    // multiplication" from "a value that happens to sit just below .5" —
+    // both normalise to the same rounded string and both round up here.
+    expect(roundDerivedCellValue(0.49999999999999994, { type: "money" })).toBe(1);
+  });
+
+  test("money: a value clearly below the half-step still rounds down", () => {
+    expect(roundDerivedCellValue(0.49, { type: "money" })).toBe(0);
+  });
+
+  test("decimal: respects the target scale", () => {
+    expect(roundDerivedCellValue(1.2345, { type: "decimal", scale: 2 })).toBe(1.23);
+  });
+
+  test("non-money/decimal targets pass through unchanged", () => {
+    expect(roundDerivedCellValue(1.23456, { type: "number" })).toBe(1.23456);
+  });
+
+  test("decimal with no scale: passes the value through unrounded instead of truncating to 0 decimals", () => {
+    expect(roundDerivedCellValue(1.2345, { type: "decimal", scale: undefined })).toBe(1.2345);
+  });
+});

package/src/engine/__tests__/engine.test.ts

@@ -1023,6 +1023,26 @@ describe("createApp", () => {
     );
   });
 
+  test("rejects embedded-list required:true combined with minItems:0", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "doc",
+        createEntity({
+          table: "Docs",
+          fields: {
+            lines: createEmbeddedListField(
+              { accountId: { type: "text" } },
+              { required: true, minItems: 0 },
+            ),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      "required:true and minItems:0",
+    );
+  });
+
   test("rejects derived cell referencing an unknown sub-field", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(

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

@@ -724,10 +724,51 @@ describe("totalsMatch (fw#1839)", () => {
     expect(schema.safeParse({ total: { amount: 30, currency: "EUR" } }).success).toBe(true);
   });
 
+  // kumiko-framework#1972: a round total (30 EUR = 3000 minor) still passes
+  // even if the major/minor conversion is silently skipped, because 30 and
+  // 3000 both "look" plausible under either interpretation. A crooked
+  // amount catches that a round-number fixture wouldn't.
+  test("accepts a crooked total (1234.56 EUR) whose minor-unit line sum matches exactly", () => {
+    const schema = buildInsertSchema(invoiceEntity());
+    const result = schema.safeParse({
+      total: { amount: 1234.56, currency: "EUR" },
+      lines: [{ amount: 100000 }, { amount: 23456 }],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  // The exact shape of the reported solon incident: a genuinely wrong total
+  // (100.00 EUR entered as if it were already minor units, i.e. 1.00 EUR)
+  // must still be rejected — proves the refinement doesn't silently pass a
+  // mismatch through by accident.
+  test("rejects a total that was itself entered/scaled wrong (100x too small)", () => {
+    const schema = buildInsertSchema(invoiceEntity());
+    const result = schema.safeParse({
+      total: { amount: 1, currency: "EUR" }, // should have been 100
+      lines: [{ amount: 10000 }], // 100.00 EUR
+    });
+    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 sibling total is not checked (nothing to compare against)", () => {
     const schema = buildUpdateSchema(invoiceEntity());
     expect(schema.safeParse({ lines: [{ amount: 1000 }, { amount: 1500 }] }).success).toBe(true);
   });
+
+  test("rejects a sibling total tagged with a currency other than the entity's default, even when the raw minor-unit amounts match", () => {
+    const schema = buildInsertSchema(invoiceEntity());
+    const result = schema.safeParse({
+      total: { amount: 30, currency: "USD" },
+      lines: [{ amount: 1000 }, { amount: 2000 }],
+    });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues.some((issue) => issue.path.join(".") === "total")).toBe(true);
+    }
+  });
 });
 
 // --- kumiko-framework#1837: derived-cell server-side recomputation — the
@@ -959,6 +1000,58 @@ describe("embedded-list derived cell recomputation (kumiko-framework#1837)", ()
       expect(row?.["amount"]).toBe(3);
     }
   });
+
+  test("a sum of scale-3 sources on a scale-2 decimal target is rounded, not rejected as over-scale", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField(
+          {
+            a: { type: "decimal", scale: 3, required: true },
+            b: { type: "decimal", scale: 3, required: true },
+            c: { type: "decimal", scale: 3, required: true },
+            total: { type: "decimal", scale: 2, required: false },
+          },
+          { derived: { total: { op: "sum", from: ["a", "b", "c"] } } },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    // Each source is in-scale for its own scale-3 field, but the sum
+    // (0.333) has 3 decimal digits — over-scale for the scale-2 target
+    // without the rounding this PR added.
+    const result = schema.safeParse({ lines: [{ a: 0.111, b: 0.111, c: 0.111 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const row = (result.data["lines"] as readonly Record<string, unknown>[])[0];
+      expect(row?.["total"]).toBe(0.33);
+    }
+  });
+
+  test("a subtract landing on a money target rounds to whole minor units", () => {
+    const entity = createEntity({
+      table: "Orders",
+      fields: {
+        lines: createEmbeddedListField(
+          {
+            gross: { type: "decimal", scale: 2, required: true },
+            refund: { type: "decimal", scale: 2, required: true },
+            total: { type: "money", required: false },
+          },
+          { derived: { total: { op: "subtract", from: ["gross", "refund"] } } },
+        ),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    // 2400.58 - 93 = 2307.58 minor units — not representable by money's
+    // integer constraint without rounding.
+    const result = schema.safeParse({ lines: [{ gross: 2400.58, refund: 93 }] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const row = (result.data["lines"] as readonly Record<string, unknown>[])[0];
+      expect(row?.["total"]).toBe(2308);
+    }
+  });
 });
 
 // --- Update schema (all partial) ---

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

@@ -1,4 +1,4 @@
-import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { BlurRegion, VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
 import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key";
 import { parseRefTarget } from "../parse-ref-target";
 import type { EmbeddedFieldDef, EntityDefinition, FeatureDefinition } from "../types";
@@ -557,6 +557,15 @@ function validateEmbeddedListBounds(
       `Embedded-list field "${fieldName}" on entity "${entityName}" has minItems ${field.minItems} greater than maxItems ${field.maxItems}.`,
     );
   }
+  // required:true means "at least one row" (schema-builder.ts falls back to
+  // minItems:1 for that); an explicit minItems:0 would silently win over
+  // that and let a required list submit empty — reject the contradiction
+  // instead of picking one side of it for the caller.
+  if (field.required === true && field.minItems === 0) {
+    throw new Error(
+      `Embedded-list field "${fieldName}" on entity "${entityName}" sets required:true and minItems:0 — these contradict each other. Drop minItems (defaults to 1) or set required:false.`,
+    );
+  }
 }
 
 function validateEmbeddedDerivedCells(
@@ -693,6 +702,31 @@ function isPositiveInt(value: number): boolean {
   return Number.isInteger(value) && value > 0;
 }
 
+// Renderers cap dimensions in practice (sharp refuses output above 0x1000000
+// pixels); 8192 per edge is generously above any real thumbnail/preview use
+// and keeps a boot-declared spec from becoming a memory-exhaustion vector.
+const MAX_VARIANT_EDGE_PX = 8192;
+// sharp's blur() accepts a sigma of 0.3..1000; anything above that throws at
+// render time, months after boot, on the first request for that variant.
+const MAX_BLUR_SIGMA = 1000;
+
+function isValidBlurRegion(region: BlurRegion): boolean {
+  const { x, y, width, height } = region;
+  return (
+    Number.isFinite(x) &&
+    Number.isFinite(y) &&
+    Number.isFinite(width) &&
+    Number.isFinite(height) &&
+    x >= 0 &&
+    y >= 0 &&
+    width >= 0 &&
+    height >= 0 &&
+    x + width <= 1 &&
+    y + height <= 1
+  );
+}
+
+// kumiko-lint-ignore complexity-budget blur/size bounds added for boot-time DoS guard
 function assertValidVariantSpec(name: string, spec: VariantSpec, where: string): void {
   if (!VARIANT_NAME_PATTERN.test(name)) {
     throw new Error(
@@ -704,15 +738,23 @@ function assertValidVariantSpec(name: string, spec: VariantSpec, where: string):
   }
   if (
     spec.size !== undefined &&
-    !(isPositiveInt(spec.size.width) && isPositiveInt(spec.size.height))
+    !(
+      isPositiveInt(spec.size.width) &&
+      isPositiveInt(spec.size.height) &&
+      spec.size.width <= MAX_VARIANT_EDGE_PX &&
+      spec.size.height <= MAX_VARIANT_EDGE_PX
+    )
   ) {
     throw new Error(
-      `Image variant "${name}" ${where} has a non-positive-integer "size" (${spec.size.width}x${spec.size.height}).`,
+      `Image variant "${name}" ${where} has an invalid "size" (${spec.size.width}x${spec.size.height}) — must be a positive integer up to ${MAX_VARIANT_EDGE_PX}px per edge.`,
     );
   }
-  if (spec.maxEdge !== undefined && !isPositiveInt(spec.maxEdge)) {
+  if (
+    spec.maxEdge !== undefined &&
+    !(isPositiveInt(spec.maxEdge) && spec.maxEdge <= MAX_VARIANT_EDGE_PX)
+  ) {
     throw new Error(
-      `Image variant "${name}" ${where} has a non-positive-integer "maxEdge" (${spec.maxEdge}).`,
+      `Image variant "${name}" ${where} has an invalid "maxEdge" (${spec.maxEdge}) — must be a positive integer up to ${MAX_VARIANT_EDGE_PX}px.`,
     );
   }
   if (spec.quality !== undefined && !(isPositiveInt(spec.quality) && spec.quality <= 100)) {
@@ -720,6 +762,23 @@ function assertValidVariantSpec(name: string, spec: VariantSpec, where: string):
       `Image variant "${name}" ${where} has "quality" ${spec.quality} — must be an integer in 1..100.`,
     );
   }
+  if (
+    spec.blur !== undefined &&
+    !(Number.isFinite(spec.blur) && spec.blur > 0 && spec.blur <= MAX_BLUR_SIGMA)
+  ) {
+    throw new Error(
+      `Image variant "${name}" ${where} has "blur" ${spec.blur} — must be a finite number in (0, ${MAX_BLUR_SIGMA}].`,
+    );
+  }
+  if (spec.blurRegions !== undefined) {
+    for (const region of spec.blurRegions) {
+      if (!isValidBlurRegion(region)) {
+        throw new Error(
+          `Image variant "${name}" ${where} has an invalid "blurRegions" entry ${JSON.stringify(region)} — x/y/width/height must be within 0..1 and x+width/y+height must not exceed 1.`,
+        );
+      }
+    }
+  }
 }
 
 // A bad spec is only visible when someone finally requests that variant —

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

@@ -8,7 +8,7 @@ import { rowMetaFieldNames } from "../../db/table-builder";
 import { isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
-import type { EntityDefinition, FeatureDefinition } from "../types";
+import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types";
 import type {
   DashboardCustomPanel,
   DashboardFilterDefinition,
@@ -27,7 +27,12 @@ import type {
 // Mirrors FIELD_TYPES_WITHOUT_WIDGET in packages/renderer/src/app/form-schema.ts.
 // Can't import it directly — renderer depends on framework, not the reverse.
 // Keep both lists in sync when a field type gains or loses an auto-wired widget.
-const NO_WIDGET_FIELD_TYPES = new Set(["jsonb", "embedded", "files", "images"]);
+const NO_WIDGET_FIELD_TYPES: ReadonlySet<FieldDefinition["type"]> = new Set([
+  "jsonb",
+  "embedded",
+  "files",
+  "images",
+]);
 
 // A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
 // entityEdit path (#1925) — a required field the user can never fill would
@@ -46,9 +51,7 @@ function validateNoWidgetRequiredField(
   if (fieldDef === undefined || !NO_WIDGET_FIELD_TYPES.has(fieldDef.type)) return;
   // Embedded LIST fields (`multiple: true`) get their own EmbeddedListField
   // grid widget (#1838) — only plain (non-list) embedded has no widget.
-  const isEmbeddedList =
-    fieldDef.type === "embedded" &&
-    (fieldDef as unknown as { multiple?: boolean }).multiple === true;
+  const isEmbeddedList = fieldDef.type === "embedded" && fieldDef.multiple === true;
   // skip: list variant has a widget — not the no-widget case this guard targets.
   if (isEmbeddedList) return;
   // skip: already read-only by spec — no fillable widget needed regardless of type.
@@ -115,13 +118,9 @@ function validateRowActionNavigateParams(
   }
 }
 
-// Wizard layouts (mode: "wizard") render one section per step — a single
-// step (or a step without a title, which would leave the progress
-// indicator blank) defeats the point, so both fail at boot rather than
-// as a broken step UI. Missing/blank titles are checked identically for
-// both section kinds — EditExtensionSection.title is required by type,
-// but that doesn't stop author code that circumvented the check from
-// passing an empty string.
+// Wizard layouts (mode: "wizard") need >= 2 titled sections — a single or
+// untitled step would leave the progress indicator blank, so both fail at
+// boot rather than as a broken step UI.
 function validateWizardLayout(
   featureName: string,
   screenId: string,
@@ -276,6 +275,25 @@ function resolveScreenTargetQn(featureName: string, target: string): string {
   return isValidQn(target) ? target : qualifyEntityName(featureName, "screen", target);
 }
 
+function validateScreenNavTarget(
+  featureName: string,
+  screenId: string,
+  screenKind: string,
+  fieldName: string,
+  value: string,
+  allScreenQns: ReadonlySet<string>,
+  screens: FeatureDefinition["screens"],
+): void {
+  const candidateQn = resolveScreenTargetQn(featureName, value);
+  if (!allScreenQns.has(candidateQn)) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${fieldName} "${value}" ` +
+        `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
+        `in this feature: ${[...Object.keys(screens)].sort().join(", ") || "(none)"}.`,
+    );
+  }
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -554,26 +572,28 @@ export function validateScreens(
         // (`<feature>:screen:<id>`) — der Renderer strippt letztere beim
         // Navigieren auf die kurze ID (lastSegment), die der nav-Router
         // app-weit auflöst (#1946).
-        const candidateQn = resolveScreenTargetQn(feature.name, screen.redirect);
-        if (!allScreenQns.has(candidateQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) redirect "${screen.redirect}" ` +
-              `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
-              `in this feature: ${[...Object.keys(feature.screens)].sort().join(", ") || "(none)"}.`,
-          );
-        }
+        validateScreenNavTarget(
+          feature.name,
+          screenId,
+          "actionForm",
+          "redirect",
+          screen.redirect,
+          allScreenQns,
+          feature.screens,
+        );
       }
       if (typeof screen.cancelTarget === "string") {
         // Gleiche Regel wie redirect — `false` (kein Cancel-Button)
         // braucht keine Validierung.
-        const candidateQn = resolveScreenTargetQn(feature.name, screen.cancelTarget);
-        if (!allScreenQns.has(candidateQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) cancelTarget "${screen.cancelTarget}" ` +
-              `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
-              `in this feature: ${[...Object.keys(feature.screens)].sort().join(", ") || "(none)"}.`,
-          );
-        }
+        validateScreenNavTarget(
+          feature.name,
+          screenId,
+          "actionForm",
+          "cancelTarget",
+          screen.cancelTarget,
+          allScreenQns,
+          feature.screens,
+        );
       }
       continue;
     }
@@ -882,14 +902,15 @@ export function validateScreens(
       if (screen.redirect !== undefined) {
         // Same rule as actionForm's redirect: short screen-ID (same-feature)
         // or a fully-qualified cross-feature QN (#1946).
-        const candidateQn = resolveScreenTargetQn(feature.name, screen.redirect);
-        if (!allScreenQns.has(candidateQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) redirect "${screen.redirect}" ` +
-              `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
-              `in this feature: ${[...Object.keys(feature.screens)].sort().join(", ") || "(none)"}.`,
-          );
-        }
+        validateScreenNavTarget(
+          feature.name,
+          screenId,
+          "entityEdit",
+          "redirect",
+          screen.redirect,
+          allScreenQns,
+          feature.screens,
+        );
       }
     }
   }

package/src/engine/embedded-derived.ts

@@ -35,7 +35,14 @@ export type DerivedCellRoundingTarget = {
  *  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);
+  // `scale` is required on the real decimal EmbeddedSubFieldDef (fields.ts:
+  // "no silent default that could truncate") — DerivedCellRoundingTarget
+  // only widens it to optional for the money/decimal split above. If it's
+  // ever missing anyway, pass the value through unrounded rather than
+  // guessing 0 decimals and truncating a value the caller never asked to round.
+  if (target.type === "decimal") {
+    return target.scale === undefined ? value : roundHalfAwayFromZero(value, target.scale);
+  }
   return value;
 }
 
@@ -45,6 +52,7 @@ function roundHalfAwayFromZero(value: number, decimals: number): number {
   // === 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.
+  // ponytail: also snaps values within ~1e-16 of a half-step up (e.g. roundHalfAwayFromZero(0.49999999999999994, 0) === 1) — deliberate, the float-noise case is far more common than a genuine near-half input.
   const scaled = Number((Math.abs(value) * factor).toPrecision(15));
   return (Math.sign(value) * Math.round(scaled)) / factor;
 }