@cosmicdrift/kumiko-framework 0.37.0 → 0.39.0

package/src/event-store/event-store.ts

@@ -14,6 +14,7 @@ import { stringifyJson } from "../utils/safe-json";
 import { isStreamArchived } from "./archive";
 import { VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
+import { toStoredEvent } from "./row-to-stored-event";
 
 export type EventMetadata = {
   readonly userId: string;
@@ -409,19 +410,3 @@ export async function* streamAllEventsByType(
     cursorId = nextCursor;
   }
 }
-
-function toStoredEvent(row: SelectedEvent): 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,
-  };
-}

package/src/event-store/index.ts

@@ -24,6 +24,7 @@ export {
   streamAllEventsByType,
 } from "./event-store";
 export { createEventsTable, eventsTable } from "./events-schema";
+export { toStoredEvent } from "./row-to-stored-event";
 export {
   createSnapshotsTable,
   type LoadAggregateWithSnapshotResult,

package/src/event-store/row-to-stored-event.ts

@@ -0,0 +1,34 @@
+import type { TenantId } from "../engine/types";
+import type { EventMetadata, StoredEvent } from "./event-store";
+
+// Minimal row shape accepted by toStoredEvent. Both SelectedEvent
+// (event-store) and StoredEventRow (event-dispatcher) satisfy it.
+type EventRow = {
+  readonly id: bigint;
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly tenantId: TenantId;
+  readonly version: number;
+  readonly type: string;
+  readonly eventVersion: number;
+  readonly payload: Record<string, unknown>;
+  readonly metadata: EventMetadata;
+  readonly createdAt: Temporal.Instant;
+  readonly createdBy: string;
+};
+
+export function toStoredEvent(row: EventRow): 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,
+  };
+}

package/src/logging/__tests__/fallback-logger.test.ts

@@ -1,8 +1,8 @@
 // createFallbackLogger Unit-Tests (Phase 1, test-luecken-integration).
 //
-// Pinnt beide Pfade des Fallback-Loggers — inkl. des non-obvious
-// Format-Unterschieds: der wrapped-Pfad schreibt "[ns] msg", der
-// console-Fallback "[ns] msg:" (trailing colon).
+// Pinnt beide Pfade des Fallback-Loggers auf das identische
+// "[ns] msg"-Format — wrapped logger und console-Fallback dürfen
+// nicht divergieren (Log-Parser/Grep-Konsistenz).
 
 import { describe, expect, mock, spyOn, test } from "bun:test";
 import { createFallbackLogger } from "../utils";
@@ -30,7 +30,7 @@ describe("createFallbackLogger", () => {
   });
 
   describe("ohne logger (console-Fallback)", () => {
-    test("schreibt auf console.error mit [namespace]-Prefix UND trailing colon", () => {
+    test("schreibt auf console.error mit [namespace]-Prefix im selben Format wie wrapped", () => {
       const spy = spyOn(console, "error").mockImplementation(() => {});
       try {
         const fallback = createFallbackLogger("boot");
@@ -38,7 +38,7 @@ describe("createFallbackLogger", () => {
         fallback.error("no logger wired", { phase: "init" });
 
         expect(spy).toHaveBeenCalledTimes(1);
-        expect(spy).toHaveBeenCalledWith("[boot] no logger wired:", { phase: "init" });
+        expect(spy).toHaveBeenCalledWith("[boot] no logger wired", { phase: "init" });
       } finally {
         spy.mockRestore();
       }

package/src/logging/utils.ts

@@ -18,7 +18,7 @@ export function createFallbackLogger(
   return {
     error(msg, data) {
       // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-      console.error(`[${namespace}] ${msg}:`, data);
+      console.error(`[${namespace}] ${msg}`, data);
     },
   };
 }

package/src/migrations/projection-table-index.ts

@@ -5,31 +5,19 @@
 // Drizzle-frei: der Tabellen-Name kommt aus dem kumiko-Symbol das
 // buildEntityTable/buildEntityTableMeta an die Table-Definition hängt.
 
+import { extractTableName } from "../db";
 import type { Registry } from "../engine/types/feature";
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-
-function getTableName(table: unknown): string {
-  if (typeof table !== "object" || table === null) {
-    throw new Error("projection-table-index: table is not a table object");
-  }
-  const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
-  if (typeof name !== "string") {
-    throw new Error("projection-table-index: table missing kumiko name symbol");
-  }
-  return name;
-}
-
 /** Index `tableName → projection-name` aus der Registry. Nur Projections mit
  *  table-Definition (single-stream + multi-stream-with-table) zählen.
  *  Side-effect-only MSPs (table omitted) haben keinen Rebuild-Sinn. */
 export function buildProjectionTableIndex(registry: Registry): ReadonlyMap<string, string> {
   const index = new Map<string, string>();
   for (const [name, def] of registry.getAllProjections()) {
-    index.set(getTableName(def.table), name);
+    index.set(extractTableName(def.table, `projection-table-index(${name})`), name);
   }
   for (const [name, def] of registry.getAllMultiStreamProjections()) {
-    if (def.table) index.set(getTableName(def.table), name);
+    if (def.table) index.set(extractTableName(def.table, `projection-table-index(${name})`), name);
   }
   return index;
 }

package/src/pipeline/__tests__/archive-stream.integration.test.ts

@@ -83,6 +83,26 @@ const archFeature = defineFeature("archtest", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  r.writeHandler(
+    "item:update",
+    z.object({ id: z.uuid(), label: z.string() }),
+    async (event, ctx) =>
+      executor.update(
+        { id: event.payload.id, changes: { label: event.payload.label } },
+        event.user,
+        ctx.db,
+        { skipOptimisticLock: true },
+      ),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "item:delete",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => executor.delete({ id: event.payload.id }, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
   r.queryHandler(
     "item:events",
     z.object({ id: z.uuid() }),
@@ -217,4 +237,59 @@ describe("archiveStream — Marten ArchiveStream equivalent", () => {
     expect(err.tenantId).toBe(admin.tenantId);
     expect(err.name).toBe("ArchivedStreamError");
   });
+
+  // The CRUD executor appends via append() + getStreamVersion(), neither of
+  // which consults the archive flag. Without the executor-level guard a
+  // PATCH/DELETE would silently land an event on an archived stream — the
+  // read-only contract honoured by ctx.appendEvent would not extend to
+  // entity-CRUD writes. These prove the guard closes that gap on both paths.
+  describe("CRUD writes honour the archive guard", () => {
+    test("executor.update on an archived stream is rejected, no event lands", async () => {
+      const { id } = await stack.http.writeOk<{ id: string }>(
+        "archtest:write:item:create",
+        { label: "before-archive" },
+        admin,
+      );
+      await stack.http.writeOk("archtest:write:item:archive", { id }, admin);
+
+      const res = await stack.http.write(
+        "archtest:write:item:update",
+        { id, label: "too-late" },
+        admin,
+      );
+      expect(res.status).toBe(500);
+
+      const raw = await loadAggregateRaw(stack.db, id, admin.tenantId, { includeArchived: true });
+      expect(raw.map((e) => e.type)).not.toContain("arch-item.updated");
+    });
+
+    test("executor.delete on an archived stream is rejected, no event lands", async () => {
+      const { id } = await stack.http.writeOk<{ id: string }>(
+        "archtest:write:item:create",
+        { label: "keep-me" },
+        admin,
+      );
+      await stack.http.writeOk("archtest:write:item:archive", { id }, admin);
+
+      const res = await stack.http.write("archtest:write:item:delete", { id }, admin);
+      expect(res.status).toBe(500);
+
+      const raw = await loadAggregateRaw(stack.db, id, admin.tenantId, { includeArchived: true });
+      expect(raw.map((e) => e.type)).not.toContain("arch-item.deleted");
+    });
+
+    test("restoreStream re-opens the stream for CRUD updates", async () => {
+      const { id } = await stack.http.writeOk<{ id: string }>(
+        "archtest:write:item:create",
+        { label: "v1" },
+        admin,
+      );
+      await stack.http.writeOk("archtest:write:item:archive", { id }, admin);
+      await stack.http.writeOk("archtest:write:item:restore", { id }, admin);
+
+      await stack.http.writeOk("archtest:write:item:update", { id, label: "v2" }, admin);
+      const raw = await loadAggregateRaw(stack.db, id, admin.tenantId);
+      expect(raw.map((e) => e.type)).toEqual(["arch-item.created", "arch-item.updated"]);
+    });
+  });
 });

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);