@cosmicdrift/kumiko-framework 0.184.0 → 0.185.0

package/package.json

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

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

@@ -85,7 +85,7 @@ describe("rehydrateCompoundTypes — Pipeline", () => {
       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" },
+      buyingPrice: { amount: 45_000, currency: "EUR", amountMinor: 4_500_000 },
     });
   });
 
@@ -98,7 +98,7 @@ describe("rehydrateCompoundTypes — Pipeline", () => {
     const round = rehydrateCompoundTypes(flattenCompoundTypes(original, mixedEntity), mixedEntity);
     // pickup bekommt utc dazu beim Read (war beim Insert nicht gesetzt)
     expect((round["pickup"] as { utc: string }).utc).toBe("2026-04-15T09:00:00Z");
-    expect(round["buyingPrice"]).toEqual({ amount: 100, currency: "EUR" });
+    expect(round["buyingPrice"]).toEqual({ amount: 100, currency: "EUR", amountMinor: 10_000 });
     expect(round["label"]).toBe("ACME");
   });
 

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

@@ -99,20 +99,33 @@ describe("flattenMoney — Insert/Update Convert (major units → minor units)",
 });
 
 describe("rehydrateMoney — Read Convert (minor units → major units)", () => {
-  test("{ <name>: minorUnits, <name>Currency: string } → { <name>: { amount: majorUnits, currency } }", () => {
+  test("{ <name>: minorUnits, <name>Currency: string } → { <name>: { amount: majorUnits, currency, amountMinor } }", () => {
     const out = rehydrateMoney({ buyingPrice: 45000, buyingPriceCurrency: "EUR" }, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 450, currency: "EUR" } });
+    expect(out).toEqual({ buyingPrice: { amount: 450, currency: "EUR", amountMinor: 45000 } });
   });
 
   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: 450, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR", amountMinor: 45000 });
   });
 
   test("fehlende Currency-Spalte fällt auf entity.defaultCurrency", () => {
     const out = rehydrateMoney({ buyingPrice: 45000 }, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR", amountMinor: 45000 });
+  });
+
+  test("amountMinor bleibt exakter Integer, amount kann Float-Drift haben (fw#1830)", () => {
+    const rows = [10, 20, 30].map(
+      (minor) =>
+        rehydrateMoney({ buyingPrice: minor, buyingPriceCurrency: "EUR" }, orderEntity)[
+          "buyingPrice"
+        ] as { amount: number; amountMinor: number },
+    );
+    const [a, b, c] = rows;
+
+    expect(a!.amountMinor + b!.amountMinor).toBe(c!.amountMinor);
+    expect(a!.amount + b!.amount).not.toBe(c!.amount);
   });
 
   test("null/undefined amount → Field wird aus Output entfernt", () => {
@@ -131,25 +144,28 @@ describe("rehydrateMoney — Read Convert (minor units → major units)", () =>
       orderEntity,
     );
     expect(out).toEqual({
-      buyingPrice: { amount: 450, currency: "EUR" },
-      sellingPrice: { amount: 600, currency: "USD" },
+      buyingPrice: { amount: 450, currency: "EUR", amountMinor: 45000 },
+      sellingPrice: { amount: 600, currency: "USD", amountMinor: 60000 },
     });
   });
 
-  test("Round-Trip: flatten dann rehydrate ergibt dasselbe, inkl. Cents", () => {
+  test("Round-Trip: flatten dann rehydrate ergibt dasselbe amount/currency, plus amountMinor", () => {
     const original = {
       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);
+    expect(rehydrated).toEqual({
+      buyingPrice: { amount: 450.5, currency: "EUR", amountMinor: 45050 },
+      sellingPrice: { amount: 56799.16, currency: "USD", amountMinor: 5679916 },
+    });
   });
 
-  test("Round-Trip primitive-Insert: flatten(450) → rehydrate → { amount:450, currency:EUR }", () => {
+  test("Round-Trip primitive-Insert: flatten(450) → rehydrate → { amount:450, currency:EUR, amountMinor:45000 }", () => {
     const flat = flattenMoney({ buyingPrice: 450 }, orderEntity);
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR", amountMinor: 45000 });
   });
 
   test("ist pure — input wird nicht mutiert", () => {
@@ -181,7 +197,7 @@ describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () =>
 
     // DB liefert dieselben Spalten zurück
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 990, currency: "USD" } });
+    expect(out).toEqual({ buyingPrice: { amount: 990, currency: "USD", amountMinor: 99_000 } });
   });
 
   test("List-Pfad: mehrere Rows hintereinander rehydraten", () => {
@@ -192,9 +208,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: 1, currency: "EUR" } },
-      { buyingPrice: { amount: 2, currency: "USD" } },
-      { buyingPrice: { amount: 3, currency: "GBP" } },
+      { buyingPrice: { amount: 1, currency: "EUR", amountMinor: 100 } },
+      { buyingPrice: { amount: 2, currency: "USD", amountMinor: 200 } },
+      { buyingPrice: { amount: 3, currency: "GBP", amountMinor: 300 } },
     ]);
   });
 });

package/src/db/money.ts

@@ -3,7 +3,10 @@
 // Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
 //   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
+//   Read-Form:   { amount, currency, amountMinor } — amount in MAJOR units again,
+//                amountMinor sits alongside as exact integer cents (fw#1830) for
+//                callers that need cent-exact comparisons (e.g. invoice sums)
+//                instead of round-tripping the float amount through /100·*100.
 //
 // table-builder.ts's moneyAmount column has always documented BIGINT as
 // "the integer minor unit" — this file used to just pass the API amount
@@ -33,7 +36,7 @@ const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
 // upgrade path once a currency needing a different scale actually lands.
 const MINOR_UNIT_SCALE = 100;
 
-function toMinorUnits(amount: number): number {
+export function toMinorUnits(amount: number): number {
   return Math.round(amount * MINOR_UNIT_SCALE);
 }
 
@@ -151,7 +154,7 @@ export function rehydrateMoney(
     const currency =
       typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
 
-    result[name] = { amount: toMajorUnits(amountMinor), currency };
+    result[name] = { amount: toMajorUnits(amountMinor), currency, amountMinor };
   }
 
   return result;

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

@@ -7,6 +7,7 @@ import { validateBoot as validateBootRaw } from "../boot-validator";
 import { createSystemConfig, createTenantConfig } from "../config-helpers";
 import {
   createDerivedField,
+  createEmbeddedListField,
   createEntity,
   createMultiSelectField,
   createTextField,
@@ -19,6 +20,23 @@ function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
   validateBootRaw(withBootValidatorFixture(features));
 }
 
+// Registriert einen Stub-Query-Handler `<entity>:list` damit der Boot-
+// Validator den Audit-Fix-#2-Check (Handler-Existenz auf der target-
+// Entity) durch lässt — used by both top-level and embedded-list
+// reference-field tests.
+function stubListHandler(
+  // biome-ignore lint/suspicious/noExplicitAny: Registrar-Typ ist generisch, hier reicht das.
+  r: any,
+  entityName: string,
+): void {
+  r.queryHandler({
+    name: `${entityName}:list`,
+    schema: z.object({}),
+    handler: async () => ({ rows: [], nextCursor: null }) as never,
+    access: { openToAll: true },
+  });
+}
+
 describe("boot-validator", () => {
   test("passes for valid features with no issues", () => {
     const features = [
@@ -2030,22 +2048,6 @@ describe("boot-validator", () => {
 
   // --- Tier 2.7e-3: ReferenceFieldDef ---
   describe("reference field (Tier 2.7e-3)", () => {
-    // Helper: registriert einen Stub-Query-Handler `<entity>:list`
-    // damit der Boot-Validator den Audit-Fix-#2-Check (Handler-
-    // Existenz auf der target-Entity) durch lässt.
-    function stubListHandler(
-      // biome-ignore lint/suspicious/noExplicitAny: Registrar-Typ ist generisch, hier reicht das.
-      r: any,
-      entityName: string,
-    ): void {
-      r.queryHandler({
-        name: `${entityName}:list`,
-        schema: z.object({}),
-        handler: async () => ({ rows: [], nextCursor: null }) as never,
-        access: { openToAll: true },
-      });
-    }
-
     test("reference auf bestehende Entity → kein Throw", () => {
       const features = [
         defineFeature("shop", (r) => {
@@ -2269,6 +2271,100 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- fw#1839: reference sub-fields of an embedded-list field get the
+  // same target/labelField/query-handler checks as a top-level reference
+  // field, so a bad "lines.productId" fails at boot instead of crashing
+  // the Combobox at runtime.
+  describe("embedded-list reference sub-field (fw#1839)", () => {
+    test("reference sub-field targeting an unknown entity → Throw with the parent.child field path", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "invoice",
+            createEntity({
+              fields: {
+                lines: createEmbeddedListField({
+                  productId: { type: "reference", entity: "ghost-entity" },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /Reference field "lines\.productId" on entity "invoice" targets unknown entity "ghost-entity"/,
+      );
+    });
+
+    test("reference sub-field with a valid target + registered list-handler → kein Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity("product", createEntity({ fields: { name: createTextField() } }));
+          stubListHandler(r, "product");
+          r.entity(
+            "invoice",
+            createEntity({
+              fields: {
+                lines: createEmbeddedListField({
+                  productId: { type: "reference", entity: "product", labelField: "name" },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("reference sub-field with a valid target but no registered list-handler → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity("product", createEntity({ fields: { name: createTextField() } }));
+          // KEIN stubListHandler — das ist der Punkt des Tests
+          r.entity(
+            "invoice",
+            createEntity({
+              fields: {
+                lines: createEmbeddedListField({
+                  productId: { type: "reference", entity: "product" },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /Reference field "lines\.productId" on entity "invoice" targets entity "product" but no list-query-handler is registered/,
+      );
+    });
+
+    test("reference sub-field labelField referencing an unknown field → Throw with the parent.child field path", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity("product", createEntity({ fields: { name: createTextField() } }));
+          stubListHandler(r, "product");
+          r.entity(
+            "invoice",
+            createEntity({
+              fields: {
+                lines: createEmbeddedListField({
+                  productId: {
+                    type: "reference",
+                    entity: "product",
+                    labelField: "ghost-field",
+                  },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /Reference field "lines\.productId" on entity "invoice" references labelField "ghost-field" which does not exist on entity "product"/,
+      );
+    });
+  });
+
   // --- Tier 2.7e-1: rowAction kind="navigate" target-existenz ---
   describe("entityList rowAction kind=navigate (Tier 2.7e-1)", () => {
     function makeFeature(targetScreen: string, withTarget: boolean) {

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

@@ -8,6 +8,7 @@ import { defineQueryHandler, defineWriteHandler } from "../define-handler";
 import {
   createBooleanField,
   createEmbeddedField,
+  createEmbeddedListField,
   createEntity,
   createMoneyField,
   createSelectField,
@@ -961,6 +962,188 @@ describe("createApp", () => {
     expect(() => createApp({ roles: ["Admin"], features: [feature] })).not.toThrow();
   });
 
+  test("rejects embedded select sub-field with empty options", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "doc",
+        createEntity({
+          table: "Docs",
+          fields: {
+            lines: createEmbeddedListField({
+              status: { type: "select", options: [] },
+            }),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow("has empty options");
+  });
+
+  test("rejects embedded-list minItems greater than maxItems", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "doc",
+        createEntity({
+          table: "Docs",
+          fields: {
+            lines: createEmbeddedListField(
+              { accountId: { type: "text" } },
+              { minItems: 3, maxItems: 1 },
+            ),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      "greater than maxItems",
+    );
+  });
+
+  test("rejects derived cell referencing an unknown sub-field", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "doc",
+        createEntity({
+          table: "Docs",
+          fields: {
+            lines: createEmbeddedListField(
+              { qty: { type: "number" }, price: { type: "number" }, total: { type: "number" } },
+              { derived: { total: { op: "multiply", from: ["qty", "unknownField"] } } },
+            ),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      'derived cell "total" reading unknown sub-field "unknownField"',
+    );
+  });
+
+  test("rejects totals referencing a non-numeric sub-field", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "doc",
+        createEntity({
+          table: "Docs",
+          fields: {
+            lines: createEmbeddedListField(
+              { label: { type: "text" }, amount: { type: "number" } },
+              { totals: ["label"] },
+            ),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      'lists "label" in totals, but it is not a number/money/decimal sub-field',
+    );
+  });
+
+  test("rejects totalsMatch entry whose sub-field is not a money sub-field (fw#1839)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          fields: {
+            total: createMoneyField({ required: true }),
+            lines: createEmbeddedListField(
+              { qty: { type: "number" } },
+              { totalsMatch: { qty: "total" } },
+            ),
+          },
+          defaultCurrency: "EUR",
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      'has a totalsMatch entry for "qty", which is not a money sub-field',
+    );
+  });
+
+  test("rejects totalsMatch entry whose sibling field is not a money field on the entity (fw#1839)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          fields: {
+            title: createTextField(),
+            lines: createEmbeddedListField(
+              { amount: { type: "money" } },
+              { totalsMatch: { amount: "title" } },
+            ),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      'mapping "amount" to sibling field "title", which is not a money field on entity "invoice"',
+    );
+  });
+
+  test("rejects totalsMatch entry whose sibling field does not exist on the entity (fw#1839)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          fields: {
+            lines: createEmbeddedListField(
+              { amount: { type: "money" } },
+              { totalsMatch: { amount: "ghostTotal" } },
+            ),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      'mapping "amount" to sibling field "ghostTotal", which is not a money field on entity "invoice"',
+    );
+  });
+
+  test("accepts a valid totalsMatch entry (fw#1839)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          fields: {
+            total: createMoneyField({ required: true }),
+            lines: createEmbeddedListField(
+              { amount: { type: "money" } },
+              { totalsMatch: { amount: "total" } },
+            ),
+          },
+          defaultCurrency: "EUR",
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).not.toThrow();
+  });
+
+  test("rejects totalsMatch on a plain (non-list) embedded field", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          fields: {
+            total: createMoneyField({ required: true }),
+            meta: createEmbeddedField(
+              { amount: { type: "money" } },
+              { totalsMatch: { amount: "total" } },
+            ),
+          },
+          defaultCurrency: "EUR",
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      "which is only valid on an embedded LIST field (multiple: true)",
+    );
+  });
+
   test("rejects transitions on non-select field", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(