@cosmicdrift/kumiko-framework 0.176.1 → 0.177.0

package/package.json

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

package/src/api/sse-broker.ts

@@ -32,6 +32,10 @@ export function createSseBroker(): SseBroker {
   // Cross-replica fanout lives one level up: the SSE + access-invalidation
   // consumers (system-hooks.ts) run delivery: "per-instance" (#1718).
   const channels = new Map<string, Map<string, SseClient>>();
+  // Set, not Map<listenerId, fn> — dedup key is callback reference. Every
+  // subscriber must pass a distinct closure (dispatch-stream.ts does, one
+  // per stream). Two subscribes with the SAME reference for the same user
+  // collapse into one listener, and the first unsubscribe kills both.
   const accessInvalidationListeners = new Map<string, Set<() => void>>();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {

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;

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

@@ -591,7 +591,7 @@ describe("boot-validator", () => {
   });
 
   test("warns when a role is used by exactly one handler, reached through the real validateBoot wiring", () => {
-    const warnSpy = spyOn(console, "warn");
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
     try {
       const features = [
         defineFeature("a", (r) => {
@@ -616,7 +616,7 @@ describe("boot-validator", () => {
   });
 
   test("does NOT warn on unique access roles by default — opt-in only (#1711)", () => {
-    const warnSpy = spyOn(console, "warn");
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
     try {
       const features = [
         defineFeature("b", (r) => {

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

@@ -15,7 +15,7 @@ describe("warnOnUniqueAccessRoles", () => {
   let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
 
   beforeEach(() => {
-    warnSpy = spyOn(console, "warn");
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
   });
 
   afterEach(() => {

package/src/pipeline/dispatch-shared.ts

@@ -73,6 +73,13 @@ import {
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 
+// Framework/pipeline stays bundled-features-free, so this can't import the
+// `tenant` feature — the literal below IS the coupling to its `timezone`
+// config key. Renaming that key (or the "tenant" feature name) must update
+// this constant too; tenant-timezone-boot.integration.test.ts boots the real
+// createTenantFeature() and would catch a drift.
+const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";
+
 export type BatchCommand = {
   readonly type: string;
   readonly payload: unknown;
@@ -522,7 +529,7 @@ export async function buildHandlerContext(
   // comes from SessionUser.timezone (set at login), else falls back to
   // tenant (createTzContext's own default). An app-injected GeoTzProvider
   // (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
-  const tenantTz = config !== undefined ? await config("tenant:config:timezone") : undefined;
+  const tenantTz = config !== undefined ? await config(TENANT_TIMEZONE_CONFIG_KEY) : undefined;
   // Guarded against garbage: an unvalidated string here (free-form config
   // key, legacy JWT claim predating validation) blows up every ctx.tz call
   // for the whole tenant with a RangeError. Fall back to UTC/tenant instead

package/src/search/purge-subject.ts

@@ -61,6 +61,66 @@ function ownershipPredicates(
   return { sql: parts.join(" OR "), params };
 }
 
+type MatchedRow = { id: string; tenant_id: string };
+
+// ponytail: LIMIT/OFFSET, not a keyset cursor — mirrors reindexEntity's same
+// tradeoff (id type varies uuid/serial across entities). A tenant-destroy
+// purge is a one-time sweep, not a hot path.
+const PURGE_BATCH_SIZE = 500;
+
+async function collectMatchingRowsForEntity(
+  db: DbRunner,
+  tableName: string,
+  whereSql: string,
+  params: readonly unknown[],
+): Promise<readonly MatchedRow[]> {
+  const rows: MatchedRow[] = [];
+  let offset = 0;
+  for (;;) {
+    const offsetN = params.length + 1;
+    const page = await executeRawQuery<MatchedRow>(
+      db,
+      `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE ${whereSql}
+        ORDER BY ${quoteIdent("id")} ASC
+        LIMIT ${PURGE_BATCH_SIZE} OFFSET $${offsetN}`,
+      [...params, offset],
+    );
+    if (page.length === 0) break;
+    rows.push(...page);
+    offset += page.length;
+    if (page.length < PURGE_BATCH_SIZE) break;
+  }
+  return rows;
+}
+
+function buildSubjectPredicate(
+  entity: EntityDefinition,
+  fields: readonly string[],
+  likePattern: string,
+  subject: SubjectId | undefined,
+): { sql: string; params: unknown[] } {
+  let paramIdx = 0;
+  const nextParam = () => ++paramIdx;
+  const params: unknown[] = [];
+  const orParts: string[] = [];
+
+  const likeN = nextParam();
+  params.push(likePattern);
+  orParts.push(
+    `(${fields.map((f) => `${quoteIdent(toSnakeCase(f))} LIKE $${likeN}`).join(" OR ")})`,
+  );
+
+  if (subject) {
+    const owned = ownershipPredicates(entity, fields, subject, nextParam);
+    if (owned) {
+      params.push(...owned.params);
+      orParts.push(`(${owned.sql})`);
+    }
+  }
+
+  return { sql: orParts.join(" OR "), params };
+}
+
 export async function purgeSearchDocumentsForSubject(
   db: DbRunner,
   features: ReadonlyMap<string, FeatureDefinition>,
@@ -78,30 +138,12 @@ export async function purgeSearchDocumentsForSubject(
       const fields = collectSearchableSubjectFields(entity);
       if (fields.length === 0) continue;
       const tableName = resolveTableName(entityName, entity, undefined);
-
-      let paramIdx = 0;
-      const nextParam = () => ++paramIdx;
-      const params: unknown[] = [];
-      const orParts: string[] = [];
-
-      const likeN = nextParam();
-      params.push(likePattern);
-      orParts.push(
-        `(${fields.map((f) => `${quoteIdent(toSnakeCase(f))} LIKE $${likeN}`).join(" OR ")})`,
-      );
-
-      if (subject) {
-        const owned = ownershipPredicates(entity, fields, subject, nextParam);
-        if (owned) {
-          params.push(...owned.params);
-          orParts.push(`(${owned.sql})`);
-        }
-      }
-
-      const rows = await executeRawQuery<{ id: string; tenant_id: string }>(
+      const predicate = buildSubjectPredicate(entity, fields, likePattern, subject);
+      const rows = await collectMatchingRowsForEntity(
         db,
-        `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE ${orParts.join(" OR ")}`,
-        params,
+        tableName,
+        predicate.sql,
+        predicate.params,
       );
       for (const row of rows) {
         const key = `${row.tenant_id}:${entityName}:${row.id}`;