@cosmicdrift/kumiko-framework 0.176.2 → 0.177.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.176.2",
+  "version": "0.177.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.176.2",
+    "@cosmicdrift/kumiko-types": "0.177.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.176.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.177.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.177.0",
+    "type": "breaking",
+    "title": "createMoneyField's amount now converts to/from minor-unit BIGINT storage (fw#1767).",
+    "detail": "flattenMoney/rehydrateMoney used to pass the API amount straight into the BIGINT column without the minor-unit (cents) conversion the column's own doc comment always claimed. A decimal amount (e.g. 56799.16) crashed the insert (float into bigint); a plain integer major-unit amount (e.g. 45000 meaning €450.00) was silently stored as 45000 minor units — 100× too small on read-back.",
+    "migration": "amount is now always major units (ordinary decimal, e.g. 56799.16) on both write and read — DB storage stays exact-integer cents automatically, no caller change needed for that direction. If you already wrote createMoneyField data under the old (unconverted) semantics, multiply stored amounts by 100 before upgrading, or reconcile after — no known production deployment currently persists money-typed data (verified solon and phronexsis are both pre-launch before this merged)."
+  },
   {
     "version": "0.167.0",
     "type": "breaking",

package/src/db/__tests__/compound-types.test.ts

@@ -49,7 +49,8 @@ describe("flattenCompoundTypes — Pipeline", () => {
     expect(flat["label"]).toBe("ACME");
     expect((flat["pickupUtc"] as Temporal.Instant).toString()).toBe("2026-04-15T09:00:00Z");
     expect(flat["pickupTz"]).toBe("Europe/Lisbon");
-    expect(flat["buyingPrice"]).toBe(45_000);
+    // flattenMoney converts major units (API) → minor units (DB, ×100).
+    expect(flat["buyingPrice"]).toBe(4_500_000);
     expect(flat["buyingPriceCurrency"]).toBe("EUR");
   });
 
@@ -75,7 +76,7 @@ describe("rehydrateCompoundTypes — Pipeline", () => {
         label: "ACME",
         pickupUtc: "2026-04-15T09:00:00Z",
         pickupTz: "Europe/Lisbon",
-        buyingPrice: 45_000,
+        buyingPrice: 4_500_000,
         buyingPriceCurrency: "EUR",
       },
       mixedEntity,
@@ -83,6 +84,7 @@ describe("rehydrateCompoundTypes — Pipeline", () => {
     expect(out).toEqual({
       label: "ACME",
       pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon", utc: "2026-04-15T09:00:00Z" },
+      // rehydrateMoney converts minor units (DB) → major units (API, ÷100).
       buyingPrice: { amount: 45_000, currency: "EUR" },
     });
   });

package/src/db/__tests__/money.test.ts

@@ -1,4 +1,8 @@
 // Pure Unit-Tests für money flatten/rehydrate Helpers.
+//
+// Contract: API-form amount is MAJOR units (56799.16 EUR), DB-form is
+// MINOR units (5679916 cents) — flattenMoney/rehydrateMoney convert at the
+// boundary (×100 / ÷100). See money.ts's file header for why this exists.
 
 import { describe, expect, test } from "bun:test";
 import { createEntity, createMoneyField, createTextField } from "../../engine";
@@ -21,24 +25,29 @@ const usdEntity: EntityDefinition = createEntity({
   },
 });
 
-describe("flattenMoney — Insert/Update Convert", () => {
-  test("{ amount, currency } → { <name>: amount, <name>Currency: currency }", () => {
-    const flat = flattenMoney({ buyingPrice: { amount: 45000, currency: "EUR" } }, orderEntity);
+describe("flattenMoney — Insert/Update Convert (major units → minor units)", () => {
+  test("{ amount, currency } → { <name>: amount*100, <name>Currency: currency }", () => {
+    const flat = flattenMoney({ buyingPrice: { amount: 450, currency: "EUR" } }, orderEntity);
     expect(flat).toEqual({ buyingPrice: 45000, buyingPriceCurrency: "EUR" });
   });
 
+  test("decimal amount rounds to the nearest cent", () => {
+    const flat = flattenMoney({ buyingPrice: { amount: 56799.16, currency: "EUR" } }, orderEntity);
+    expect(flat).toEqual({ buyingPrice: 5679916, buyingPriceCurrency: "EUR" });
+  });
+
   test("primitive number (legacy) wird akzeptiert + entity.defaultCurrency angehängt", () => {
-    const flat = flattenMoney({ buyingPrice: 45000 }, orderEntity);
+    const flat = flattenMoney({ buyingPrice: 450 }, orderEntity);
     expect(flat).toEqual({ buyingPrice: 45000, buyingPriceCurrency: "EUR" });
   });
 
   test("primitive number nutzt USD wenn entity.defaultCurrency = USD", () => {
-    const flat = flattenMoney({ fee: 199 }, usdEntity);
+    const flat = flattenMoney({ fee: 1.99 }, usdEntity);
     expect(flat).toEqual({ fee: 199, feeCurrency: "USD" });
   });
 
   test("expliziter <name>Currency im Payload überschreibt nicht", () => {
-    const flat = flattenMoney({ buyingPrice: 45000, buyingPriceCurrency: "USD" }, orderEntity);
+    const flat = flattenMoney({ buyingPrice: 450, buyingPriceCurrency: "USD" }, orderEntity);
     // Wenn bereits gesetzt, nicht überschreiben — caller-explicit gewinnt
     expect(flat["buyingPriceCurrency"]).toBe("USD");
   });
@@ -46,8 +55,8 @@ describe("flattenMoney — Insert/Update Convert", () => {
   test("mehrere money-Felder am gleichen Object", () => {
     const flat = flattenMoney(
       {
-        buyingPrice: { amount: 45000, currency: "EUR" },
-        sellingPrice: { amount: 60000, currency: "USD" },
+        buyingPrice: { amount: 450, currency: "EUR" },
+        sellingPrice: { amount: 600, currency: "USD" },
       },
       orderEntity,
     );
@@ -61,7 +70,7 @@ describe("flattenMoney — Insert/Update Convert", () => {
 
   test("andere Felder bleiben unverändert", () => {
     const flat = flattenMoney(
-      { label: "Premium", buyingPrice: { amount: 100, currency: "EUR" } },
+      { label: "Premium", buyingPrice: { amount: 1, currency: "EUR" } },
       orderEntity,
     );
     expect(flat["label"]).toBe("Premium");
@@ -77,33 +86,33 @@ describe("flattenMoney — Insert/Update Convert", () => {
     const noCurrencyEntity: EntityDefinition = createEntity({
       fields: { fee: createMoneyField() },
     });
-    const flat = flattenMoney({ fee: 50 }, noCurrencyEntity);
+    const flat = flattenMoney({ fee: 0.5 }, noCurrencyEntity);
     expect(flat["feeCurrency"]).toBe("EUR");
   });
 
   test("ist pure — input wird nicht mutiert", () => {
-    const input = { buyingPrice: { amount: 45000, currency: "EUR" } };
+    const input = { buyingPrice: { amount: 450, currency: "EUR" } };
     const before = JSON.stringify(input);
     flattenMoney(input, orderEntity);
     expect(JSON.stringify(input)).toBe(before);
   });
 });
 
-describe("rehydrateMoney — Read Convert", () => {
-  test("{ <name>: number, <name>Currency: string } → { <name>: { amount, currency } }", () => {
+describe("rehydrateMoney — Read Convert (minor units → major units)", () => {
+  test("{ <name>: minorUnits, <name>Currency: string } → { <name>: { amount: majorUnits, currency } }", () => {
     const out = rehydrateMoney({ buyingPrice: 45000, buyingPriceCurrency: "EUR" }, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 45000, currency: "EUR" } });
+    expect(out).toEqual({ buyingPrice: { amount: 450, currency: "EUR" } });
   });
 
   test("PG-BIGINT als String wird zu number gecastet", () => {
     // Postgres-driver liefert BIGINT manchmal als String (>2^53 sicher).
     const out = rehydrateMoney({ buyingPrice: "45000", buyingPriceCurrency: "EUR" }, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
   });
 
   test("fehlende Currency-Spalte fällt auf entity.defaultCurrency", () => {
     const out = rehydrateMoney({ buyingPrice: 45000 }, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
   });
 
   test("null/undefined amount → Field wird aus Output entfernt", () => {
@@ -122,25 +131,25 @@ describe("rehydrateMoney — Read Convert", () => {
       orderEntity,
     );
     expect(out).toEqual({
-      buyingPrice: { amount: 45000, currency: "EUR" },
-      sellingPrice: { amount: 60000, currency: "USD" },
+      buyingPrice: { amount: 450, currency: "EUR" },
+      sellingPrice: { amount: 600, currency: "USD" },
     });
   });
 
-  test("Round-Trip: flatten dann rehydrate ergibt dasselbe", () => {
+  test("Round-Trip: flatten dann rehydrate ergibt dasselbe, inkl. Cents", () => {
     const original = {
-      buyingPrice: { amount: 45000, currency: "EUR" },
-      sellingPrice: { amount: 60000, currency: "USD" },
+      buyingPrice: { amount: 450.5, currency: "EUR" },
+      sellingPrice: { amount: 56799.16, currency: "USD" },
     };
     const flat = flattenMoney(original, orderEntity);
     const rehydrated = rehydrateMoney(flat, orderEntity);
     expect(rehydrated).toEqual(original);
   });
 
-  test("Round-Trip primitive-Insert: flatten(45000) → rehydrate → { amount:45000, currency:EUR }", () => {
-    const flat = flattenMoney({ buyingPrice: 45000 }, orderEntity);
+  test("Round-Trip primitive-Insert: flatten(450) → rehydrate → { amount:450, currency:EUR }", () => {
+    const flat = flattenMoney({ buyingPrice: 450 }, orderEntity);
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
   });
 
   test("ist pure — input wird nicht mutiert", () => {
@@ -166,13 +175,13 @@ describe("rehydrateMoney — Read Convert", () => {
 describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () => {
   test("Update-Changes-Payload mit money geht durch flatten + zurück durch rehydrate", () => {
     // Simuliert was der Executor macht: changes → flatten → DB → rehydrate
-    const changes = { buyingPrice: { amount: 99_000, currency: "USD" } };
+    const changes = { buyingPrice: { amount: 990, currency: "USD" } };
     const flat = flattenMoney(changes, orderEntity);
     expect(flat).toEqual({ buyingPrice: 99_000, buyingPriceCurrency: "USD" });
 
     // DB liefert dieselben Spalten zurück
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 99_000, currency: "USD" } });
+    expect(out).toEqual({ buyingPrice: { amount: 990, currency: "USD" } });
   });
 
   test("List-Pfad: mehrere Rows hintereinander rehydraten", () => {
@@ -183,9 +192,9 @@ describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () =>
     ];
     const apiRows = dbRows.map((r) => rehydrateMoney(r, orderEntity));
     expect(apiRows).toEqual([
-      { buyingPrice: { amount: 100, currency: "EUR" } },
-      { buyingPrice: { amount: 200, currency: "USD" } },
-      { buyingPrice: { amount: 300, currency: "GBP" } },
+      { buyingPrice: { amount: 1, currency: "EUR" } },
+      { buyingPrice: { amount: 2, currency: "USD" } },
+      { buyingPrice: { amount: 3, currency: "GBP" } },
     ]);
   });
 });

package/src/db/money.ts

@@ -1,9 +1,19 @@
 // Auto-Convert für money-Felder im DB-Layer.
 //
 // Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
-//   API-Form:    { amount, currency } | number (permissiv für Legacy)
-//   DB-Form:     <name> BIGINT + <name>Currency TEXT
-//   Read-Form:   { amount, currency }
+//   API-Form:    { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
+//   DB-Form:     <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
+//   Read-Form:   { amount, currency } — amount in MAJOR units again
+//
+// table-builder.ts's moneyAmount column has always documented BIGINT as
+// "the integer minor unit" — this file used to just pass the API amount
+// through unconverted, silently violating that contract: a caller doing
+// the ergonomic thing (passing 56799.16) got a float into a bigint column
+// (driver error) or, worse, an integer major-unit amount (56799) got
+// stored as if it were already minor units — 100× too small on read back.
+// MINOR_UNIT_SCALE fixes that at the boundary so every caller can just
+// pass/receive ordinary decimal amounts; DB storage stays exact-integer
+// cents (no float drift in SUM()/aggregate queries).
 //
 // Permissiv-Insert: primitive number wird als amount akzeptiert (Legacy aus
 // pre-Stufe-3-Samples). Currency fällt dann auf entity.defaultCurrency
@@ -18,6 +28,19 @@ import { DEFAULT_CURRENCIES } from "../engine/types";
 
 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;
+
+function toMinorUnits(amount: number): number {
+  return Math.round(amount * MINOR_UNIT_SCALE);
+}
+
+function toMajorUnits(amountMinor: number): number {
+  return amountMinor / MINOR_UNIT_SCALE;
+}
+
 /**
  * API → DB: money-Felder zu zwei flachen Spalten flatten.
  *
@@ -68,7 +91,7 @@ export function flattenMoney(
     }
 
     delete result[name];
-    result[name] = amount;
+    result[name] = toMinorUnits(amount);
     result[`${name}Currency`] = currency;
   }
 
@@ -103,18 +126,18 @@ export function rehydrateMoney(
       continue;
     }
 
-    let amount: number;
+    let amountMinor: number;
     if (typeof amountRaw === "number") {
-      amount = amountRaw;
+      amountMinor = amountRaw;
     } else if (typeof amountRaw === "bigint") {
-      amount = Number(amountRaw);
-      if (Number.isNaN(amount)) {
+      amountMinor = Number(amountRaw);
+      if (Number.isNaN(amountMinor)) {
         throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a number`);
       }
     } else if (typeof amountRaw === "string" && amountRaw !== "") {
       // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
-      amount = Number(amountRaw);
-      if (Number.isNaN(amount)) {
+      amountMinor = Number(amountRaw);
+      if (Number.isNaN(amountMinor)) {
         throw new Error(
           `rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a number — DB corruption?`,
         );
@@ -128,7 +151,7 @@ export function rehydrateMoney(
     const currency =
       typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
 
-    result[name] = { amount, currency };
+    result[name] = { amount: toMajorUnits(amountMinor), currency };
   }
 
   return result;