@cosmicdrift/kumiko-framework 0.36.0 → 0.38.0

package/src/pipeline/dispatcher-utils.ts

@@ -6,13 +6,7 @@ import type {
   SessionUser,
   WriteResult,
 } from "../engine/types";
-import {
-  type FieldIssue,
-  InternalError,
-  isKumikoError,
-  type KumikoError,
-  type WriteErrorInfo,
-} from "../errors";
+import { type FieldIssue, toKumikoError, type WriteErrorInfo } from "../errors";
 
 export type FailedWriteResult = Extract<WriteResult, { isSuccess: false }>;
 
@@ -182,8 +176,4 @@ export function resolveType(type: HandlerType): string {
   return typeof type === "string" ? type : type.name;
 }
 
-export function wrapToKumiko(e: unknown): KumikoError {
-  if (isKumikoError(e)) return e;
-  if (e instanceof Error) return new InternalError({ cause: e });
-  return new InternalError({ message: String(e) });
-}
+export const wrapToKumiko = toKumikoError;

package/src/pipeline/event-consumer-state.ts

@@ -97,6 +97,7 @@ export type ConsumerStatus = (typeof ConsumerStatuses)[keyof typeof ConsumerStat
 // table is already present (second stack in the same test DB, prod boot
 // after migration), skip cleanly.
 //
+// guard:dup-ok — intentionale Parallele zu createProjectionStateTable; symmetrische State-Tabellen by design
 export async function createEventConsumerStateTable(db: DbConnection): Promise<void> {
   // skip: table already exists — bootstrap is called from multiple paths
   if (await tableExists(db, "public.kumiko_event_consumers")) return;

package/src/pipeline/event-dispatcher.ts

@@ -16,6 +16,7 @@ import {
   EVENTS_PUBSUB_CHANNEL,
   eventsTable,
   getEventsHighWaterMark,
+  toStoredEvent as rowToStoredEvent,
   type StoredEvent,
 } from "../event-store";
 import {
@@ -298,22 +299,6 @@ type DeliveryOutcome = {
   readonly failed: number;
 };
 
-function rowToStoredEvent(row: StoredEventRow): StoredEvent {
-  return {
-    id: String(row.id),
-    aggregateId: row.aggregateId,
-    aggregateType: row.aggregateType,
-    tenantId: row.tenantId,
-    version: row.version,
-    type: row.type,
-    eventVersion: row.eventVersion,
-    payload: row.payload,
-    metadata: row.metadata,
-    createdAt: row.createdAt,
-    createdBy: row.createdBy,
-  };
-}
-
 // Deliver events to the consumer's handler in events.id order. Halt-on-
 // poison: a throw breaks the loop, the cursor stays at the last successful
 // event, and attempts climb. At maxAttempts the caller persists status=
@@ -743,18 +728,13 @@ async function requireConsumerRow(
   return row;
 }
 
-export async function restartConsumer(
+async function applyConsumerStatusTransition(
   db: DbConnection,
   name: string,
-  instanceId: string = SHARED_INSTANCE_SENTINEL,
+  instanceId: string,
+  targetStatus: "idle" | "disabled",
 ): Promise<ConsumerRecoveryState> {
-  const before = await requireConsumerRow(db, name, instanceId);
-  if (before.status !== "dead") {
-    throw new Error(
-      `Consumer "${name}" (instance_id="${instanceId}") is not dead (status="${before.status}"). Restart only applies to dead consumers; use "enable" for a disabled one.`,
-    );
-  }
-  const raw = await updateConsumerStatusReturning(db, name, instanceId, "idle");
+  const raw = await updateConsumerStatusReturning(db, name, instanceId, targetStatus);
   const updated =
     raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
   if (!updated) {
@@ -765,21 +745,27 @@ export async function restartConsumer(
   return normalizeConsumerState(updated);
 }
 
-export async function disableConsumer(
+export async function restartConsumer(
   db: DbConnection,
   name: string,
   instanceId: string = SHARED_INSTANCE_SENTINEL,
 ): Promise<ConsumerRecoveryState> {
-  await requireConsumerRow(db, name, instanceId);
-  const raw = await updateConsumerStatusReturning(db, name, instanceId, "disabled");
-  const updated =
-    raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
-  if (!updated) {
+  const before = await requireConsumerRow(db, name, instanceId);
+  if (before.status !== "dead") {
     throw new Error(
-      `Consumer "${name}" (instance_id="${instanceId}") vanished between read and write — retry.`,
+      `Consumer "${name}" (instance_id="${instanceId}") is not dead (status="${before.status}"). Restart only applies to dead consumers; use "enable" for a disabled one.`,
     );
   }
-  return normalizeConsumerState(updated);
+  return applyConsumerStatusTransition(db, name, instanceId, "idle");
+}
+
+export async function disableConsumer(
+  db: DbConnection,
+  name: string,
+  instanceId: string = SHARED_INSTANCE_SENTINEL,
+): Promise<ConsumerRecoveryState> {
+  await requireConsumerRow(db, name, instanceId);
+  return applyConsumerStatusTransition(db, name, instanceId, "disabled");
 }
 
 export async function enableConsumer(
@@ -793,15 +779,7 @@ export async function enableConsumer(
       `Consumer "${name}" (instance_id="${instanceId}") is not disabled (status="${before.status}"). Enable only flips disabled → idle; use "restart" for a dead consumer.`,
     );
   }
-  const raw = await updateConsumerStatusReturning(db, name, instanceId, "idle");
-  const updated =
-    raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
-  if (!updated) {
-    throw new Error(
-      `Consumer "${name}" (instance_id="${instanceId}") vanished between read and write — retry.`,
-    );
-  }
-  return normalizeConsumerState(updated);
+  return applyConsumerStatusTransition(db, name, instanceId, "idle");
 }
 
 // skipPoisonEvent advances the cursor past the first event after the
@@ -948,6 +926,7 @@ export type ConsumerProgress = {
 // post-commit — lag is the primary signal for backpressure, dead consumers,
 // or dispatcher stalls. Programmatic callers can map the result to a
 // `kumiko_consumer_lag{name}` Prometheus gauge.
+// guard:dup-ok — intentionale Parallele zu getAllProjectionProgress; Consumer ≠ Projection (verschiedene Subsysteme)
 export async function getAllConsumerProgress(
   db: DbConnection,
   registeredNames: readonly string[],

package/src/pipeline/msp-rebuild.ts

@@ -1,3 +1,4 @@
+import { extractTableName } from "../db";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import {
   markConsumerRebuildFailed,
@@ -91,16 +92,16 @@ export async function rebuildMultiStreamProjection(
   const { db, registry } = deps;
   const msp = registry.getAllMultiStreamProjections().get(mspName);
   if (!msp) {
-    throw new Error(
-      `MultiStreamProjection "${mspName}" is not registered. Known: ${
+    throw new InternalError({
+      message: `MultiStreamProjection "${mspName}" is not registered. Known: ${
         [...registry.getAllMultiStreamProjections().keys()].join(", ") || "(none)"
       }`,
-    );
+    });
   }
   if (!msp.table) {
-    throw new Error(
-      `MultiStreamProjection "${mspName}" has no backing table — it is a pure side-effect consumer (webhooks, notifications, external sync). Rebuild would re-invoke those side-effects by replaying the log. For poison events use bun kumiko consumer skip / restart; there is no analogous "rebuild" concept for side-effect sinks.`,
-    );
+    throw new InternalError({
+      message: `MultiStreamProjection "${mspName}" has no backing table — it is a pure side-effect consumer (webhooks, notifications, external sync). Rebuild would re-invoke those side-effects by replaying the log. For poison events use bun kumiko consumer skip / restart; there is no analogous "rebuild" concept for side-effect sinks.`,
+    });
   }
 
   const startedAt = Date.now();
@@ -113,7 +114,7 @@ export async function rebuildMultiStreamProjection(
       await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
 
       const mspTable = msp.table as NonNullable<typeof msp.table>;
-      const tableName = getTableName(mspTable);
+      const tableName = extractTableName(mspTable, "msp-rebuild");
       await truncateTable(tx, tableName);
 
       const subscribedTypes = Object.keys(msp.apply);
@@ -204,15 +205,3 @@ export async function rebuildMultiStreamProjection(
   deps.onMetrics?.(result);
   return result;
 }
-
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-function getTableName(table: unknown): string {
-  if (typeof table !== "object" || table === null) {
-    throw new InternalError({ message: "msp-rebuild: msp.table is not a pgTable object" });
-  }
-  const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
-  if (typeof name !== "string") {
-    throw new InternalError({ message: "msp-rebuild: msp.table missing drizzle name symbol" });
-  }
-  return name;
-}

package/src/pipeline/projection-rebuild.ts

@@ -1,3 +1,4 @@
+import { extractTableName } from "../db";
 import type { DbConnection, DbTx } from "../db/connection";
 import {
   finalizeProjectionRebuild,
@@ -96,7 +97,7 @@ export async function rebuildProjection(
     await db.begin(async (tx: DbTx) => {
       await markProjectionRebuilding(tx, projectionName);
 
-      const tableName = getTableName(projection.table);
+      const tableName = extractTableName(projection.table, "projection-rebuild");
       await truncateTable(tx, tableName);
 
       // Stream events in chronological order for every source. The event
@@ -199,18 +200,6 @@ export async function rebuildProjection(
   return result;
 }
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-function getTableName(table: unknown): string {
-  if (typeof table !== "object" || table === null) {
-    throw new Error("projection-rebuild: projection.table is not a pgTable object");
-  }
-  const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
-  if (typeof name !== "string") {
-    throw new Error("projection-rebuild: projection.table missing drizzle name symbol");
-  }
-  return name;
-}
-
 // Read-only status for one projection. Returns null if the projection was
 // registered but never rebuilt (no row yet).
 export async function getProjectionState(

package/src/pipeline/system-hooks.ts

@@ -95,6 +95,21 @@ function reconstructStateForSearch(
   return (payload["previous"] as Record<string, unknown> | undefined) ?? {}; // @cast-boundary engine-payload
 }
 
+// buildSearchDocument runs per save — without dedup a colliding contributor
+// key would spam one warn line per write on the hotpath.
+const warnedKeyCollisions = new Set<string>();
+function warnOncePerKeyCollision(entityName: string, key: string, isBaseField: boolean): void {
+  const dedupKey = `${entityName}:${key}`;
+  if (!warnedKeyCollisions.has(dedupKey)) {
+    warnedKeyCollisions.add(dedupKey);
+    const collidesWith = isBaseField ? `Stammfield "${key}"` : `earlier contributor key "${key}"`;
+    console.warn(
+      `[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
+        `${collidesWith} — keeping the first value. Rename the contributor key.`,
+    );
+  }
+}
+
 // Build a SearchDocument from raw field-state. Parallel to the old
 // buildSearchDocument that took a SaveContext — same selector logic, just
 // a different input shape.
@@ -149,14 +164,12 @@ export async function buildSearchDocument(
   // searchable Stammfield is dropped (not silently merged over the real value)
   // and warned. A jsonb custom-field that happens to share a Stammfield name
   // must not shadow the indexed Stammfield.
+  const baseFieldKeys = new Set(Object.keys(fields));
   for (const contribute of extensions) {
     const contributed = await contribute({ entityName, entityId, state });
     for (const [key, value] of Object.entries(contributed)) {
       if (Object.hasOwn(fields, key)) {
-        console.warn(
-          `[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
-            `Stammfield "${key}" — keeping the base field. Rename the contributor key.`,
-        );
+        warnOncePerKeyCollision(entityName, key, baseFieldKeys.has(key));
         continue;
       }
       fields[key] = value;

package/src/random/words.ts

@@ -13,9 +13,10 @@
 //   - Aussprechbar in Deutsch UND Englisch (User-Telefon-Support)
 //   - Keine Wörter mit ambiguer Bedeutung in Englisch+Deutsch
 //
-// 191 × 173 = 33.043 saubere Kombinationen — bei einer Standard-
-// Hashing-Kollision (Birthday-Bound) reicht das für ~180 Tenants ohne
-// Suffix. Drüber kommt der Suffix-Pfad in generateUniqueName.
+// 191 × 173 = 33.043 saubere Kombinationen. Birthday-Bound: ab ~180
+// Tenants wird kumulativ die erste Kollision wahrscheinlich (~50%);
+// pro Einzel-Draw bleibt p(Kollision) < 1% (vgl. generate.ts). Bei
+// Kollision greift der Suffix-Pfad in generateUniqueName.
 //
 // Erweiterung: weitere Wörter unten anhängen reicht (sortiert ist
 // hilfreich für Reviews aber nicht erforderlich). Caller können auch

package/src/stack/test-stack.ts

@@ -212,7 +212,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   if (enabledHooks.includes("search")) {
     const searchableFields: string[] = [];
     for (const feature of options.features) {
-      for (const [, entity] of Object.entries(feature.entities)) {
+      for (const [, entity] of Object.entries(feature.entities ?? {})) {
         for (const [fieldName, field] of Object.entries(entity.fields)) {
           if (field.type === "text" && field.searchable) {
             searchableFields.push(fieldName);