@cosmicdrift/kumiko-framework 0.207.0 → 0.208.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.207.0",
+  "version": "0.208.1",
   "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>",
@@ -190,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.207.0",
+    "@cosmicdrift/kumiko-types": "0.208.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -206,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.207.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.208.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/event-store-executor-list.integration.test.ts

@@ -126,6 +126,81 @@ describe("event-store-executor.list — offset + totalCount (Tier 2.6d)", () =>
   });
 });
 
+describe("event-store-executor.list — stable order (#2198)", () => {
+  const exec = createEventStoreExecutor(table, entity, { entityName: "pagerItem" });
+
+  test("offset paging mit identischem sort-Wert: keine Row auf beiden Seiten, Union = alle Rows", async () => {
+    // All rows share the same rank value. Postgres picks a Top-N heapsort
+    // for LIMIT queries, which is not stable across ties — and different
+    // offsets sort differently-sized heaps (LIMIT 3 OFFSET 0 sorts the
+    // top 3, LIMIT 3 OFFSET 3 sorts the top 6), so without an id
+    // tie-breaker the same row can surface on multiple pages while
+    // another is skipped entirely. Needs enough rows + small enough
+    // pages to make the heap sizes diverge; 10 rows / page 5 (the
+    // previous setup) was too forgiving and stayed green without the fix.
+    const total = 25;
+    const pageSize = 3;
+    for (let i = 0; i < total; i++) {
+      await exec.create({ title: `item-${String(i).padStart(3, "0")}`, rank: 1 }, admin, tdb);
+    }
+    const page1 = await exec.list(
+      { limit: pageSize, offset: 0, sort: "rank", sortDirection: "asc" },
+      admin,
+      tdb,
+    );
+    const page2 = await exec.list(
+      { limit: pageSize, offset: pageSize, sort: "rank", sortDirection: "asc" },
+      admin,
+      tdb,
+    );
+    const ids1 = page1.rows.map((r) => r["id"]);
+    const ids2 = page2.rows.map((r) => r["id"]);
+    expect(ids1.filter((id) => ids2.includes(id))).toHaveLength(0);
+
+    const allIds = new Set<unknown>();
+    for (let offset = 0; offset < total; offset += pageSize) {
+      const page = await exec.list(
+        { limit: pageSize, offset, sort: "rank", sortDirection: "asc" },
+        admin,
+        tdb,
+      );
+      for (const id of page.rows.map((r) => r["id"])) allIds.add(id);
+    }
+    expect(allIds.size).toBe(total);
+  });
+
+  test("cursor paging ohne sort: jede Row genau einmal", async () => {
+    // Plain sequential inserts keep heap physical order == uuidv7 id order,
+    // so a Seq Scan without ORDER BY happens to come out sorted anyway and
+    // the missing-ORDER-BY bug stays invisible. Delete half the rows and
+    // VACUUM to free their heap space, then insert more rows so their
+    // (higher) uuidv7 ids get placed into the reused (earlier) pages —
+    // now physical scan order diverges from id order.
+    const client = asRawClient(testDb.db);
+    for (let i = 0; i < 100; i++) {
+      await exec.create({ title: `item-${String(i).padStart(3, "0")}`, rank: i }, admin, tdb);
+    }
+    await client.unsafe(`DELETE FROM read_pager_items WHERE rank::int % 2 = 1`);
+    await client.unsafe(`VACUUM read_pager_items`);
+    for (let i = 100; i < 150; i++) {
+      await exec.create({ title: `item-${String(i).padStart(3, "0")}`, rank: i }, admin, tdb);
+    }
+    const countRow = await client.unsafe(`SELECT count(*)::int AS c FROM read_pager_items`);
+    const total = (countRow as unknown as Array<{ c: number }>)[0]?.c ?? 0;
+
+    const seenIds: string[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < total + 5; page++) {
+      const res = await exec.list({ limit: 3, cursor }, admin, tdb);
+      seenIds.push(...res.rows.map((r) => r["id"] as string));
+      if (res.nextCursor === null) break;
+      cursor = res.nextCursor;
+    }
+    expect(seenIds).toHaveLength(total);
+    expect(new Set(seenIds).size).toBe(total);
+  });
+});
+
 describe("event-store-executor.list — filter (Tier 2.7c)", () => {
   const exec = createEventStoreExecutor(table, entity, { entityName: "pagerItem" });
 

package/src/db/event-store-executor-read.ts

@@ -200,8 +200,8 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
 
       const orderByClause =
         payload.sort && table[payload.sort]
-          ? ` ORDER BY ${colSql(payload.sort)} ${payload.sortDirection === "desc" ? "DESC" : "ASC"}`
-          : "";
+          ? ` ORDER BY ${colSql(payload.sort)} ${payload.sortDirection === "desc" ? "DESC" : "ASC"}, ${colSql("id")} ASC`
+          : ` ORDER BY ${colSql("id")} ASC`;
       const useOffset = !payload.cursor && offset > 0;
       const offsetClause = useOffset ? ` OFFSET ${offset}` : "";
 

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

@@ -77,15 +77,15 @@ describe("validateBoot — i18n surface keys", () => {
     expect(() => validateBoot([feature])).toThrow(/required translation key missing/);
   });
 
-  test("throws when de/en locale is missing", () => {
+  test("does not require every locale on every key", () => {
     const feature = defineFeature("demo", (r) => {
       r.nav({ id: "home", label: "demo:nav.home" });
       r.translations({
         keys: {
-          "demo:nav.home": { de: "Start", en: "" },
+          "demo:nav.home": { de: "Start" },
         },
       });
     });
-    expect(() => validateBoot([feature])).toThrow(/missing locale\(s\): en/);
+    expect(() => validateBoot([feature])).not.toThrow();
   });
 });

package/src/engine/boot-validator/i18n-keys.ts

@@ -1,7 +1,6 @@
 import {
   buildEffectiveTranslationKeys,
   featureHasI18nSurface,
-  findTranslationLocaleGaps,
   requiredKeysFromFeature,
   requiredKeysFromNav,
   requiredKeysFromScreen,
@@ -75,10 +74,4 @@ export function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]):
       throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}"`);
     }
   }
-
-  for (const gap of findTranslationLocaleGaps(features)) {
-    throw new Error(
-      `[i18n] Feature "${gap.featureName}": key "${gap.key}" missing locale(s): ${gap.missingLocales.join(", ")}`,
-    );
-  }
 }

package/src/i18n/__tests__/mail-registry.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { hasMailTranslations, mailT, registerMailTranslations } from "../mail-registry";
+
+describe("mail-registry", () => {
+  registerMailTranslations("en", { "test.hi": "Hello {name}" });
+
+  test("falls back to English when locale is missing", () => {
+    expect(mailT("fr", "test.hi", { name: "Ada" })).toBe("Hello Ada");
+  });
+
+  test("registered locale wins", () => {
+    registerMailTranslations("de", { "test.hi": "Hallo {name}" });
+    expect(mailT("de", "test.hi", { name: "Ada" })).toBe("Hallo Ada");
+  });
+});
+
+test("hasMailTranslations is true only for registered locales", () => {
+  expect(hasMailTranslations("en")).toBe(true);
+  expect(hasMailTranslations("fr")).toBe(false);
+  registerMailTranslations("de", { "test.hi": "Hallo {name}" });
+  expect(hasMailTranslations("de")).toBe(true);
+  expect(hasMailTranslations("de-AT")).toBe(true);
+});

package/src/i18n/index.ts

@@ -1,5 +1,7 @@
 import type { Registry, TranslationKeys } from "../engine/types";
 
+export { hasMailTranslations, mailT, registerMailTranslations } from "./mail-registry";
+
 export type I18nOptions = {
   defaultLocale: string;
 };

package/src/i18n/mail-registry.ts

@@ -0,0 +1,26 @@
+const tables = new Map<string, Readonly<Record<string, string>>>();
+
+export function registerMailTranslations(
+  locale: string,
+  bundle: Readonly<Record<string, string>>,
+): void {
+  const prev = tables.get(locale) ?? {};
+  tables.set(locale, { ...prev, ...bundle });
+}
+
+export function hasMailTranslations(locale: string): boolean {
+  const root = locale.split("-")[0] ?? locale;
+  return tables.has(locale) || tables.has(root);
+}
+
+export function mailT(
+  locale: string,
+  key: string,
+  params?: Readonly<Record<string, string>>,
+): string {
+  const root = locale.split("-")[0] ?? locale;
+  const raw =
+    tables.get(locale)?.[key] ?? tables.get(root)?.[key] ?? tables.get("en")?.[key] ?? key;
+  if (params === undefined) return raw;
+  return raw.replace(/\{(\w+)\}/g, (_, name: string) => params[name] ?? `{${name}}`);
+}

package/src/i18n/required-surface-keys.ts

@@ -322,23 +322,9 @@ export type TranslationLocaleGap = {
   readonly missingLocales: readonly string[];
 };
 
-const REQUIRED_LOCALES = ["de", "en"] as const;
-
+/** Locale completeness is opt-in via @cosmicdrift/kumiko-locale-* packages. */
 export function findTranslationLocaleGaps(
-  features: readonly FeatureDefinition[],
+  _features: readonly FeatureDefinition[],
 ): readonly TranslationLocaleGap[] {
-  const gaps: TranslationLocaleGap[] = [];
-  for (const feature of features) {
-    for (const [localKey, entry] of Object.entries(feature.translations ?? {})) {
-      const missing = REQUIRED_LOCALES.filter((locale) => (entry[locale] ?? "").length === 0);
-      if (missing.length > 0) {
-        gaps.push({
-          featureName: feature.name,
-          key: localKey,
-          missingLocales: missing,
-        });
-      }
-    }
-  }
-  return gaps;
+  return [];
 }