@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/system-hooks.ts

@@ -0,0 +1,190 @@
+import type { SseBroker } from "../api/sse-broker";
+import type { DbRow } from "../db/connection";
+import { tenantChannel } from "../engine/constants";
+import type { EntityId, Registry } from "../engine/types";
+import type { SearchAdapter, SearchDocument } from "../search/types";
+import type { EventConsumer } from "./event-dispatcher";
+
+// --- Search Index Consumer (async, via event-dispatcher) ---
+//
+// Search-Indexierung läuft seit D.4 als async EventConsumer über den event-
+// dispatcher, nicht mehr als synchroner postSave/postDelete-hook. Das
+// spiegelt Marten's ISubscription-Pattern: ein einziger async Pfad für alle
+// non-inline side-effects.
+//
+// Event → Search-Op Mapping:
+//
+//   <entity>.created     → index(tenantId, doc)
+//   <entity>.updated     → index(tenantId, doc)   // re-index mit neuem state
+//   <entity>.restored    → index(tenantId, doc)   // wiederbeleben
+//   <entity>.deleted     → remove(tenantId, type, id)
+//
+// Der Document-State wird aus dem Event rekonstruiert (kein SaveContext
+// mehr available). Regel:
+//
+//   created:  state = event.payload            // ganze entity ist im payload
+//   updated:  state = { ...previous, ...changes }  // rekonstruiert neuen state
+//   restored: state = event.payload.previous   // restored field-set
+//
+// Sensitive fields sind aus dem event log bereits gestrippt (event-store-
+// executor.ts), also kriegt der Search-Index sie ebenfalls nicht — das ist
+// die gleiche Garantie wie vorher beim postSave-hook.
+//
+// Batch-Variante gibt's aktuell nicht mehr — jeder Event triggert einen
+// eigenen index()-call. Wenn Performance nach Scale-Messung das erfordert,
+// kann der event-dispatcher später eine Batch-Handler-Variante bekommen.
+export const SEARCH_CONSUMER_NAME = "system:consumer:search";
+
+export function createSearchEventConsumer(
+  searchAdapter: SearchAdapter,
+  registry: Registry,
+): EventConsumer {
+  return {
+    name: SEARCH_CONSUMER_NAME,
+    handler: async (event) => {
+      const entityName = event.aggregateType;
+      const verb = event.type.split(".").pop();
+      const tenantId = event.tenantId;
+
+      // skip: delete takes an early-return after removing the index entry —
+      // the "reconstruct state" path below only makes sense for created/
+      // updated/restored, which carry field data in the payload.
+      if (verb === "deleted") {
+        await searchAdapter.remove(tenantId, entityName, event.aggregateId);
+        return;
+      }
+
+      if (verb !== "created" && verb !== "updated" && verb !== "restored") {
+        // skip: other event types (custom domain events, future verbs) don't
+        // carry a search-indexable payload shape. If a future feature needs
+        // them indexed, it registers its own multiStreamProjection.
+        return;
+      }
+
+      const state = reconstructStateForSearch(event.payload, verb);
+      const doc = buildSearchDocument(entityName, event.aggregateId, state, registry);
+      if (!doc) {
+        // skip: entity isn't searchable (no searchable fields declared)
+        return;
+      }
+      await searchAdapter.index(tenantId, doc);
+    },
+  };
+}
+
+// Rebuild the entity-state a search index needs from the event-payload alone.
+// Three shapes to handle — see event-store-executor.ts for the emitter side.
+function reconstructStateForSearch(
+  payload: Record<string, unknown>,
+  verb: "created" | "updated" | "restored",
+): Record<string, unknown> {
+  if (verb === "created") {
+    // create: payload IS the entity (minus sensitive fields, already
+    // stripped by event-store-executor)
+    return payload;
+  }
+  if (verb === "updated") {
+    // update: payload = { changes, previous }. Merge to get the new state
+    // the index should reflect. Sensitive fields already filtered out.
+    const previous = (payload["previous"] as Record<string, unknown> | undefined) ?? {}; // @cast-boundary engine-payload
+    const changes = (payload["changes"] as Record<string, unknown> | undefined) ?? {}; // @cast-boundary engine-payload
+    return { ...previous, ...changes };
+  }
+  // restored: payload = { previous }. The restored entity is whatever the
+  // field-values were at delete time — restore copies them back verbatim.
+  return (payload["previous"] as Record<string, unknown> | undefined) ?? {}; // @cast-boundary engine-payload
+}
+
+// Build a SearchDocument from raw field-state. Parallel to the old
+// buildSearchDocument that took a SaveContext — same selector logic, just
+// a different input shape.
+function buildSearchDocument(
+  entityName: string,
+  entityId: EntityId,
+  state: Record<string, unknown>,
+  registry: Registry,
+): SearchDocument | null {
+  const entity = registry.getEntity(entityName);
+  if (!entity) return null;
+
+  const searchableFields = registry.getSearchableFields(entityName);
+  if (searchableFields.length === 0) return null;
+
+  const embeddedFields = new Set<string>();
+  for (const [fname, fdef] of Object.entries(entity.fields)) {
+    if (fdef.type === "embedded") embeddedFields.add(fname);
+  }
+
+  const fields: Record<string, unknown> = {};
+  for (const f of searchableFields) {
+    const underscoreIdx = f.indexOf("_");
+    if (underscoreIdx > 0) {
+      const parentKey = f.slice(0, underscoreIdx);
+      if (embeddedFields.has(parentKey)) {
+        const subKey = f.slice(underscoreIdx + 1);
+        const parent = state[parentKey];
+        if (parent && typeof parent === "object") {
+          const value = (parent as DbRow)[subKey];
+          if (value !== undefined) fields[f] = value;
+        }
+        continue;
+      }
+    }
+    if (state[f] !== undefined) {
+      fields[f] = state[f];
+    }
+  }
+
+  return {
+    entityType: entityName,
+    entityId,
+    weight: entity.searchWeight ?? 1,
+    fields,
+  };
+}
+
+// --- SSE Broadcast (async, via event-dispatcher) ---
+//
+// SSE-Broadcast läuft seit D.3 als async EventConsumer über den event-
+// dispatcher, nicht mehr als synchroner postSave/postDelete-hook. Das hat
+// zwei Konsequenzen:
+//
+// 1. **Event-native Payload-Shape.** Der SSE-event spiegelt den StoredEvent:
+//    `type` ist event.type ("user.created", "unit.updated"), `data` enthält
+//    id, aggregateType, version und die event-payload — keine künstliche
+//    "system:event:<entity>:<verb>" Hülle mehr. Clients haben direkten
+//    Zugriff auf `payload.changes` + `payload.previous` (wie im event-log).
+// 2. **Eventual consistency statt Read-after-Write.** Ein SSE-Event kommt
+//    ~10–100ms nach dem HTTP-200 (abhängig von pollIntervalMs). UI-Clients
+//    die auf optimistic-update setzen merken das nicht; strictly-waiting
+//    Clients müssten poll-after-write.
+//
+// Tests drain deterministisch via `await stack.eventDispatcher.runOnce()`.
+export const SSE_BROADCAST_CONSUMER_NAME = "system:consumer:sse-broadcast";
+
+export function createSseBroadcastEventConsumer(sseBroker: SseBroker): EventConsumer {
+  return {
+    name: SSE_BROADCAST_CONSUMER_NAME,
+    // Per-instance delivery: each API process has its own pool of SSE
+    // clients and its own cursor. Every instance reads every event
+    // independently and pushes to its local clients. Without this, in a
+    // split-deploy (API-1/API-2 + Worker, Welle 2.5), only ONE API
+    // instance would pick up each event (shared-cursor SKIP LOCKED) and
+    // the other instance's clients would never see updates. SSE clients
+    // pin to a specific API process via the HTTP long-poll; cross-process
+    // delivery isn't solvable by sharing a cursor.
+    delivery: "per-instance",
+    handler: async (event) => {
+      sseBroker.pushToChannel(tenantChannel(event.tenantId), {
+        type: event.type,
+        data: {
+          id: event.aggregateId,
+          aggregateType: event.aggregateType,
+          version: event.version,
+          payload: event.payload,
+          createdAt: event.createdAt,
+        },
+      });
+    },
+  };
+}

package/src/random/__tests__/generate.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "vitest";
+import {
+  ADJECTIVES,
+  generateAdjNounName,
+  generateNoConfusableId,
+  generateUniqueName,
+  NOUNS,
+} from "../index";
+
+describe("generateAdjNounName", () => {
+  test("default: <adj>-<noun> aus den Standard-Listen", () => {
+    const name = generateAdjNounName();
+    const [adj, noun, ...rest] = name.split("-");
+    expect(rest).toEqual([]);
+    expect(ADJECTIVES).toContain(adj);
+    expect(NOUNS).toContain(noun);
+  });
+
+  test("custom separator", () => {
+    const name = generateAdjNounName({ separator: "_" });
+    expect(name).toMatch(/^[a-z]+_[a-z]+$/);
+    const [adj, noun] = name.split("_");
+    expect(ADJECTIVES).toContain(adj);
+    expect(NOUNS).toContain(noun);
+  });
+
+  test("mit suffix: <adj>-<noun>-<suffix>", () => {
+    const name = generateAdjNounName({ suffix: { length: 3 } });
+    const parts = name.split("-");
+    expect(parts).toHaveLength(3);
+    const [adj, noun, suffix] = parts;
+    expect(ADJECTIVES).toContain(adj);
+    expect(NOUNS).toContain(noun);
+    expect(suffix).toMatch(/^[a-z2-9]{3}$/);
+    // No-confusable: keine 0/1/o/l/i
+    expect(suffix).not.toMatch(/[01oli]/);
+  });
+
+  test("custom adjectives + nouns Wahl", () => {
+    const name = generateAdjNounName({
+      adjectives: ["rapid"],
+      nouns: ["receiver"],
+    });
+    expect(name).toBe("rapid-receiver");
+  });
+
+  test("Statistical: 100 Generierungen → mindestens 5 verschiedene", () => {
+    const names = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      names.add(generateAdjNounName());
+    }
+    // 22500 combos, 100 picks → erwartete Diversität ist hoch.
+    // Lower bound 5 fängt nur einen kompletten RNG-Defekt.
+    expect(names.size).toBeGreaterThan(5);
+  });
+});
+
+describe("generateNoConfusableId", () => {
+  test("returns string der gewünschten Länge", () => {
+    expect(generateNoConfusableId(8)).toHaveLength(8);
+    expect(generateNoConfusableId(1)).toHaveLength(1);
+  });
+
+  test("nur Zeichen aus dem no-confusable-Alphabet", () => {
+    for (let i = 0; i < 50; i++) {
+      const id = generateNoConfusableId(10);
+      expect(id).toMatch(/^[a-z2-9]+$/);
+      expect(id).not.toMatch(/[01oli]/);
+    }
+  });
+
+  test("length < 1 wirft", () => {
+    expect(() => generateNoConfusableId(0)).toThrow(/length must be ≥ 1/);
+    expect(() => generateNoConfusableId(-3)).toThrow(/length must be ≥ 1/);
+  });
+
+  test("Statistical: 200 IDs der Länge 8 → alle unique", () => {
+    // 32^8 = 1 Trillion combos → 200 picks haben praktisch 0 % Kollision.
+    const ids = new Set<string>();
+    for (let i = 0; i < 200; i++) {
+      ids.add(generateNoConfusableId(8));
+    }
+    expect(ids.size).toBe(200);
+  });
+});
+
+describe("generateUniqueName", () => {
+  test("isAvailable=true beim ersten Wurf → returnt clean (kein Suffix)", async () => {
+    const seen: string[] = [];
+    const name = await generateUniqueName({
+      isAvailable: async (n) => {
+        seen.push(n);
+        return true;
+      },
+    });
+    expect(seen).toHaveLength(1);
+    expect(name).toBe(seen[0]);
+    // Clean = nur 2 Teile (adj + noun), kein suffix
+    expect(name.split("-")).toHaveLength(2);
+  });
+
+  test("nach 3 Kollisionen wechselt zu Suffix-Mode", async () => {
+    const tried: string[] = [];
+    const name = await generateUniqueName({
+      maxCleanAttempts: 3,
+      isAvailable: async (n) => {
+        tried.push(n);
+        // Erste 3 sind belegt, der 4. Versuch (suffix-mode) wins.
+        return tried.length === 4;
+      },
+    });
+    expect(tried).toHaveLength(4);
+    // Erste 3 ohne suffix
+    for (let i = 0; i < 3; i++) {
+      expect(tried[i]?.split("-")).toHaveLength(2);
+    }
+    // 4. Versuch hat suffix
+    expect(tried[3]?.split("-")).toHaveLength(3);
+    expect(name).toBe(tried[3]);
+  });
+
+  test("wirft wenn maxTotalAttempts erschöpft", async () => {
+    await expect(
+      generateUniqueName({
+        isAvailable: async () => false,
+        maxTotalAttempts: 5,
+      }),
+    ).rejects.toThrow(/failed to find available name after 5 attempts/);
+  });
+
+  test("respektiert custom Wortlisten", async () => {
+    const name = await generateUniqueName({
+      isAvailable: async () => true,
+      adjectives: ["bold"],
+      nouns: ["receiver"],
+    });
+    expect(name).toBe("bold-receiver");
+  });
+
+  test("config-Validierung: maxClean > maxTotal wirft", async () => {
+    await expect(
+      generateUniqueName({
+        isAvailable: async () => true,
+        maxCleanAttempts: 10,
+        maxTotalAttempts: 5,
+      }),
+    ).rejects.toThrow(/maxCleanAttempts.*must not exceed maxTotalAttempts/);
+  });
+});

package/src/random/generate.ts

@@ -0,0 +1,141 @@
+// Random-Generator für human-readable Resource-Identifier:
+//   - Tenant-Keys ("happy-cloud", "swift-river-k8x")
+//   - Webhook-Subscriber-Slugs ("bold-falcon-receiver" mit custom nouns)
+//   - API-Key-Display-Names (3 Vorschläge anbieten beim Create)
+//   - Tenant-Subdomain-Vorschläge im Subdomain-Setup-Screen
+//   - Test-Fixtures mit lesbaren Identifiern
+//
+// NICHT für Security-Token (CSRF, Session, API-Keys, OAuth-State,
+// Reset-Token). Math.random() ist nicht kryptografisch unvorhersagbar.
+// Authority-binding für Tenant-Keys läuft über JWT + DB-Lookup, nicht
+// über Slug-Geheimhaltung — der Slug darf erratbar sein.
+//
+// Universal-safe: Math.random() läuft in Bun, Node, Metro/RN, Expo-Web.
+// Keine node:crypto-Imports.
+
+import { ADJECTIVES, NOUNS } from "./words";
+
+// Alphabet ohne handgetippt verwechselbare Zeichen:
+//   - keine 0/O (Null vs Großbuchstabe O)
+//   - keine 1/l/I (Eins vs Kleinbuchstabe L vs Großbuchstabe I)
+// Resultat: 32 Zeichen, sicher beim Telefon-Buchstabieren UND beim
+// Mailtext-Copy-Paste in fremde Schriftarten.
+const NO_CONFUSABLE_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz";
+const NO_CONFUSABLE_CHARS: readonly string[] = Object.freeze(NO_CONFUSABLE_ALPHABET.split(""));
+
+function pickRandom<T>(arr: readonly T[]): T {
+  if (arr.length === 0) {
+    throw new Error("pickRandom: cannot pick from empty array");
+  }
+  const value = arr[Math.floor(Math.random() * arr.length)];
+  // Length-Check oben garantiert dass index in-range ist.
+  if (value === undefined) {
+    throw new Error("pickRandom: indexed value undefined (sparse array?)");
+  }
+  return value;
+}
+
+export type AdjNounNameOptions = {
+  /** Trennzeichen zwischen adj/noun (und ggf. suffix). Default "-". */
+  readonly separator?: string;
+  /** Wenn gesetzt, wird ein random-suffix der Länge .length angehängt
+   *  (no-confusable-Alphabet). Empfohlen 3 Zeichen = 32^3 = 32.768
+   *  zusätzliche Combinations pro Wortpaar. */
+  readonly suffix?: { readonly length: number };
+  /** Custom Adjective-Liste — default ADJECTIVES (150 generic). */
+  readonly adjectives?: readonly string[];
+  /** Custom Noun-Liste — default NOUNS (150 generic). Apps die Domain-
+   *  spezifische Slugs wollen (z.B. webhook-feature mit eigenen
+   *  -receiver/-listener-Substantiven) reichen ihre eigene Liste. */
+  readonly nouns?: readonly string[];
+};
+
+/** Sync Generator: produziert "happy-cloud" oder "happy-cloud-k8x"
+ *  (mit suffix). Kein Conflict-Check — Caller verantwortlich für
+ *  Uniqueness, oder generateUniqueName() für die async Variante. */
+export function generateAdjNounName(options: AdjNounNameOptions = {}): string {
+  const sep = options.separator ?? "-";
+  const adjs = options.adjectives ?? ADJECTIVES;
+  const nouns = options.nouns ?? NOUNS;
+  let name = `${pickRandom(adjs)}${sep}${pickRandom(nouns)}`;
+  if (options.suffix) {
+    name = `${name}${sep}${generateNoConfusableId(options.suffix.length)}`;
+  }
+  return name;
+}
+
+/** Random-String aus dem no-confusable-Alphabet. Für Suffix-bei-Kollision
+ *  oder als standalone short-IDs (z.B. Webhook-Verifizierungs-Codes
+ *  zum Vorlesen am Telefon). length ≥ 1. */
+export function generateNoConfusableId(length: number): string {
+  if (length < 1) {
+    throw new Error(`generateNoConfusableId: length must be ≥ 1 (got ${length})`);
+  }
+  let id = "";
+  for (let i = 0; i < length; i++) {
+    id += pickRandom(NO_CONFUSABLE_CHARS);
+  }
+  return id;
+}
+
+export type GenerateUniqueNameOptions = {
+  /** Caller-Predicate. Returns true wenn der Name noch nicht vergeben
+   *  ist (typisch: DB-Query "select where slug=$1" → row count === 0). */
+  readonly isAvailable: (name: string) => Promise<boolean>;
+  /** Max Versuche OHNE Suffix bevor wir auf suffix-mode wechseln.
+   *  Default 3. Bei 22.500 Default-Combos und ~150 existierenden
+   *  Tenants liegt p(Kollision) < 1% — 3 Versuche reichen weit. */
+  readonly maxCleanAttempts?: number;
+  /** Suffix-Länge bei Kollision-Mode. Default 3 (= 32.768 Combinations
+   *  pro Wortpaar). */
+  readonly suffixLength?: number;
+  /** Hard-Cap an Total-Versuchen bevor wir aufgeben. Default 20.
+   *  Praktisch nie erreicht — wenn doch, ist die Wortliste leer oder
+   *  isAvailable() returnt durchgängig false (DB-Bug). */
+  readonly maxTotalAttempts?: number;
+  readonly separator?: string;
+  readonly adjectives?: readonly string[];
+  readonly nouns?: readonly string[];
+};
+
+/** Generiert einen unique Adj-Noun-Slug indem es bis zu maxCleanAttempts
+ *  saubere Wortpaare versucht, danach mit random Suffix bis maxTotal-
+ *  Attempts. Wirft wenn auch das nicht hilft (= caller hat ein Bug
+ *  mit isAvailable, oder die Wortliste ist defekt).
+ *
+ *  Beispiel:
+ *    const slug = await generateUniqueName({
+ *      isAvailable: async (s) =>
+ *        !(await db.select().from(tenants).where(eq(tenants.tenantKey, s)).then(r => r.length > 0)),
+ *    });
+ *    // → "happy-cloud" oder "happy-cloud-k8x" bei Kollision
+ */
+export async function generateUniqueName(options: GenerateUniqueNameOptions): Promise<string> {
+  const maxClean = options.maxCleanAttempts ?? 3;
+  const suffixLength = options.suffixLength ?? 3;
+  const maxTotal = options.maxTotalAttempts ?? 20;
+  if (maxClean > maxTotal) {
+    throw new Error(
+      `generateUniqueName: maxCleanAttempts (${maxClean}) must not exceed maxTotalAttempts (${maxTotal})`,
+    );
+  }
+
+  const baseOptions: AdjNounNameOptions = {
+    ...(options.separator !== undefined && { separator: options.separator }),
+    ...(options.adjectives !== undefined && { adjectives: options.adjectives }),
+    ...(options.nouns !== undefined && { nouns: options.nouns }),
+  };
+
+  for (let i = 0; i < maxTotal; i++) {
+    const useSuffix = i >= maxClean;
+    const name = generateAdjNounName(
+      useSuffix ? { ...baseOptions, suffix: { length: suffixLength } } : baseOptions,
+    );
+    if (await options.isAvailable(name)) return name;
+  }
+
+  throw new Error(
+    `generateUniqueName: failed to find available name after ${maxTotal} attempts. ` +
+      `Wordlists may be exhausted, or isAvailable() returns false unconditionally.`,
+  );
+}

package/src/random/index.ts

@@ -0,0 +1,8 @@
+export {
+  type AdjNounNameOptions,
+  type GenerateUniqueNameOptions,
+  generateAdjNounName,
+  generateNoConfusableId,
+  generateUniqueName,
+} from "./generate";
+export { ADJECTIVES, NOUNS } from "./words";