@cosmicdrift/kumiko-framework 0.2.3 → 0.4.0

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

@@ -1,4 +1,5 @@
 import { and, asc, desc, eq, gt, inArray, lt, ne, type SQL, sql } from "drizzle-orm";
+import type { AnyPgColumn } from "drizzle-orm/pg-core";
 import { requestContext } from "../api/request-context";
 import { checkWriteFieldOwnership } from "../engine/field-access";
 import {
@@ -32,7 +33,7 @@ import {
 } from "../event-store";
 import type { EntityCache } from "../pipeline/entity-cache";
 import type { SearchAdapter } from "../search/types";
-import { generateId } from "../utils";
+import { assertUnreachable, generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 import type { DbRow } from "./connection";
@@ -54,8 +55,11 @@ type Table = TableColumns<any>;
 // vs-Type-Compat ohnehin Kontrolle was reinkommt.
 //
 // Empty-array IN ist explizit "no match" (SQL false), nicht "match all".
-// biome-ignore lint/suspicious/noExplicitAny: Drizzle-Column ist generic; siehe oben.
-function buildFilterCondition(col: any, op: "eq" | "ne" | "lt" | "gt" | "in", value: unknown): SQL {
+function buildFilterCondition(
+  col: AnyPgColumn,
+  op: "eq" | "ne" | "lt" | "gt" | "in",
+  value: unknown,
+): SQL {
   switch (op) {
     case "eq":
       return eq(col, value as never); // @cast-boundary db-operator
@@ -70,6 +74,8 @@ function buildFilterCondition(col: any, op: "eq" | "ne" | "lt" | "gt" | "in", va
         return inArray(col, value as never); // @cast-boundary db-operator
       }
       return sql`false`;
+    default:
+      assertUnreachable(op, "filter op");
   }
 }
 
@@ -281,7 +287,7 @@ export function createEventStoreExecutor(
     }
     // Drizzle's variadic `and()` is typed `SQL | undefined`; conditions is
     // guaranteed non-empty above (we pushed at least one).
-    return and(...conditions) as SQL;
+    return and(...conditions) as SQL; // @cast-boundary db-operator
   }
 
   async function loadById(id: EntityId, db: TenantDb): Promise<Record<string, unknown> | null> {
@@ -295,7 +301,7 @@ export function createEventStoreExecutor(
       // Respect an explicit id in the payload (seed pattern, SCIM import). Without
       // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
       // event payload so defaults + downstream consumers don't see a redundant id field.
-      const explicitId = typeof payload["id"] === "string" ? (payload["id"] as string) : undefined;
+      const explicitId = typeof payload["id"] === "string" ? (payload["id"] as string) : undefined; // @cast-boundary engine-payload
       const aggregateId = explicitId ?? generateId();
       const { id: _id, ...payloadWithoutId } = payload;
       const data = applyDefaults(payloadWithoutId);
@@ -561,7 +567,7 @@ export function createEventStoreExecutor(
           isSuccess: true,
           data: {
             kind: "save",
-            id: data["id"] as EntityId,
+            id: data["id"] as EntityId, // @cast-boundary engine-payload
             data,
             changes: payload.changes,
             previous,
@@ -793,7 +799,7 @@ export function createEventStoreExecutor(
         }
       }
 
-      const whereClause = conditions.length > 0 ? (and(...conditions) as SQL) : undefined;
+      const whereClause = conditions.length > 0 ? (and(...conditions) as SQL) : undefined; // @cast-boundary db-operator
       let query = whereClause
         ? db.select().from(table).where(whereClause)
         : db.select().from(table);
@@ -822,13 +828,13 @@ export function createEventStoreExecutor(
         await entityCache.mset(
           user.tenantId,
           entityName,
-          rows.map((r) => ({ id: r["id"] as EntityId, data: r })),
+          rows.map((r) => ({ id: r["id"] as EntityId, data: r })), // @cast-boundary engine-payload
         );
       }
 
       const lastRow = rows[rows.length - 1];
       const nextCursor =
-        rows.length === limit && lastRow ? encodeCursor(lastRow["id"] as string) : null;
+        rows.length === limit && lastRow ? encodeCursor(lastRow["id"] as string) : null; // @cast-boundary engine-payload
 
       // total: extra COUNT(*) — nur wenn explizit angefordert (Pager-UI).
       // Postgres-Cost ist O(table-scan) ohne Filter, mit Filter so teuer
@@ -842,7 +848,7 @@ export function createEventStoreExecutor(
           const countQuery = whereClause
             ? db.select({ count: sql<number>`count(*)::int` }).from(table).where(whereClause)
             : db.select({ count: sql<number>`count(*)::int` }).from(table);
-          const countRow = (await countQuery) as Array<{ count: number }>;
+          const countRow = (await countQuery) as Array<{ count: number }>; // @cast-boundary db-row
           total = countRow[0]?.count ?? 0;
         }
       }
@@ -872,7 +878,7 @@ export function createEventStoreExecutor(
             const checked = await db
               .select()
               .from(table)
-              .where(and(idFilter(payload.id), ownership.sql) as SQL)
+              .where(and(idFilter(payload.id), ownership.sql) as SQL) // @cast-boundary db-operator
               .limit(1);
             if (checked.length === 0) return null;
           }
@@ -887,11 +893,11 @@ export function createEventStoreExecutor(
       // thread the ownership clause.
       const baseFilter = idFilter(payload.id);
       const whereClause =
-        ownership.kind === "sql" ? (and(baseFilter, ownership.sql) as SQL) : baseFilter;
+        ownership.kind === "sql" ? (and(baseFilter, ownership.sql) as SQL) : baseFilter; // @cast-boundary db-operator
       const rows = (await db.select().from(table).where(whereClause).limit(1)) as Record<
         string,
         unknown
-      >[];
+      >[]; // @cast-boundary db-row
       const raw = rows[0];
       if (!raw) return null;
       const row = rehydrateCompoundTypes(raw, entity);

package/src/db/located-timestamp.ts

@@ -51,7 +51,7 @@ export function flattenLocatedTimestamp(
         `flattenLocatedTimestamp: field "${name}" expects { at, tz } or { utc, tz } object, got ${typeof raw}`,
       );
     }
-    const pair = raw as { at?: string; tz?: string; utc?: string };
+    const pair = raw as { at?: string; tz?: string; utc?: string }; // @cast-boundary schema-walk
 
     delete result[name];
 

package/src/db/money.ts

@@ -26,6 +26,11 @@ const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
  *
  * Pure — mutiert nicht.
  */
+interface MoneyPair {
+  amount: number;
+  currency?: string;
+}
+
 export function flattenMoney(
   payload: Record<string, unknown>,
   entity: EntityDefinition,
@@ -42,8 +47,13 @@ export function flattenMoney(
     let amount: number;
     let currency: string;
 
-    if (typeof raw === "object" && "amount" in raw) {
-      const pair = raw as { amount: number; currency?: string };
+    if (
+      typeof raw === "object" &&
+      raw !== null &&
+      "amount" in raw &&
+      typeof (raw as MoneyPair).amount === "number" // @cast-boundary schema-walk
+    ) {
+      const pair = raw as MoneyPair; // @cast-boundary schema-walk
       amount = pair.amount;
       currency = pair.currency ?? fallbackCurrency;
     } else if (typeof raw === "number") {

package/src/db/pg-error.ts

@@ -20,7 +20,7 @@ export function extractPgError(e: unknown): PgErrorInfo | null {
   for (const layer of layers) {
     // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
     const code = (layer as { code?: string }).code;
-    const constraintName = (layer as { constraint_name?: string }).constraint_name;
+    const constraintName = (layer as { constraint_name?: string }).constraint_name; // @cast-boundary error-details
     if (code !== undefined || constraintName !== undefined) {
       return { code, constraint_name: constraintName };
     }

package/src/db/row-helpers.ts

@@ -49,5 +49,5 @@ export async function fetchOne<TRow = DbRow>(
 ): Promise<TRow | undefined> {
   const where = conditions.length === 1 ? conditions[0] : and(...conditions);
   const rows = await db.select().from(table).where(where).limit(1);
-  return rows[0] as TRow | undefined;
+  return rows[0] as TRow | undefined; // @cast-boundary db-row
 }

package/src/db/table-builder.ts

@@ -133,10 +133,8 @@ function fieldToColumns(
       // wrapper-feld mit boolean-flag oder discriminierte-union.
       return { [name]: jsonb(snakeName).default({}).notNull() };
     case "date": {
-      // TODO(Sprint G): semantisch falsch — `type:"date"` sollte
-      // Temporal.PlainDate sein (PG `date` Spalte, kein TZ). Heute aliased auf
-      // instant() = TIMESTAMPTZ damit Caller die gleiche API nutzen wie für
-      // type:"timestamp". Echte PlainDate-Migration kommt nach Sprint F.
+      // `type:"date"` aliased auf instant() = TIMESTAMPTZ. Echte
+      // PlainDate-Migration (PG `date` Spalte, kein TZ) kommt später.
       const col = instant(snakeName);
       return { [name]: field.required ? col.notNull() : col };
     }
@@ -478,7 +476,7 @@ export function buildDrizzleTable<E extends EntityDefinition>(
           def.name ?? `${tableName}_${def.columns.map((c) => toSnakeCase(c)).join("_")}_${suffix}`;
         const builder = def.unique === true ? uniqueIndex(indexName) : index(indexName);
         // biome-ignore lint/suspicious/noExplicitAny: drizzle's .on(...cols) is variadic generic
-        let chain = (builder.on as any)(...cols);
+        let chain = (builder.on as any)(...cols); // @cast-boundary drizzle-bridge
         if (def.where !== undefined) {
           // Partial-Index: drizzle's IndexBuilder.where(SQL) emittiert das
           // `WHERE <condition>` ans Ende der `CREATE [UNIQUE] INDEX`-DDL.

package/src/db/tenant-db.ts

@@ -1,5 +1,5 @@
-import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { and, type Column, eq, getTableName, or, type SQL } from "drizzle-orm";
+import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
 import type { TableColumns } from "./dialect";
@@ -148,7 +148,7 @@ export function createTenantDb(
   // types don't include PromiseLike. Cast via this helper so the double-
   // cast is named and lives in exactly one place per scope.
   function asDrizzleThenable<T>(builder: unknown): PromiseLike<T> {
-    return builder as PromiseLike<T>;
+    return builder as PromiseLike<T>; // @cast-boundary engine-bridge
   }
 
   // Wrap a DB query promise in a `db.query` span + emit the DB duration
@@ -229,7 +229,7 @@ export function createTenantDb(
     const ownOrGlobal = or(
       eq(table["tenantId"], tenantId),
       eq(table["tenantId"], SYSTEM_TENANT_ID),
-    ) as SQL;
+    ) as SQL; // @cast-boundary db-operator
     return extra.length > 0 ? and(ownOrGlobal, ...extra) : ownOrGlobal;
   }
 
@@ -309,7 +309,7 @@ export function createTenantDb(
           reject ?? undefined,
         );
       },
-    } as TenantSelectQuery;
+    } as TenantSelectQuery; // @cast-boundary drizzle-bridge
   }
 
   // --- Where helper for update/delete ---
@@ -342,7 +342,7 @@ export function createTenantDb(
               return withDbSpan<Record<string, unknown>[]>(
                 "insert",
                 table,
-                () => q.returning() as PromiseLike<Record<string, unknown>[]>,
+                () => q.returning() as PromiseLike<Record<string, unknown>[]>, // @cast-boundary db-runner
               );
             },
             onConflictDoUpdate(spec: ConflictUpdate) {
@@ -370,7 +370,7 @@ export function createTenantDb(
                 reject,
               );
             },
-          } as TenantInsertValues;
+          } as TenantInsertValues; // @cast-boundary drizzle-bridge
         },
       };
     },
@@ -387,7 +387,7 @@ export function createTenantDb(
                   return withDbSpan<Record<string, unknown>[]>(
                     "update",
                     table,
-                    () => wq.returning() as PromiseLike<Record<string, unknown>[]>,
+                    () => wq.returning() as PromiseLike<Record<string, unknown>[]>, // @cast-boundary db-runner
                   );
                 },
                 // biome-ignore lint/suspicious/noThenProperty: thenable for await
@@ -397,7 +397,7 @@ export function createTenantDb(
                     reject,
                   );
                 },
-              } as TenantUpdateWhere;
+              } as TenantUpdateWhere; // @cast-boundary drizzle-bridge
             },
             returning(): PromiseLike<Record<string, unknown>[]> {
               return Promise.reject(
@@ -416,7 +416,7 @@ export function createTenantDb(
                 ),
               ).then(resolve, reject);
             },
-          } as TenantUpdateSet;
+          } as TenantUpdateSet; // @cast-boundary drizzle-bridge
         },
       };
     },

package/src/engine/__tests__/_pipeline-test-utils.ts

@@ -0,0 +1,23 @@
+// Shared helpers for unit-tests of pipeline.ts / run-pipeline.ts and the
+// step-builders. The minimal-ctx helper was 4 lines duplicated in every
+// pipeline-* test file; centralised here for the M.1.6 cleanup-pass
+// (Followup #7 splitting).
+//
+// Real-ctx integration lives in pipeline-handler.integration.ts —
+// these helpers are deliberately for the no-DB tests where step-args
+// + assembly + boot-time guards are what's exercised.
+
+import type { HandlerContext } from "../types/handlers";
+
+/**
+ * Returns an empty object cast as HandlerContext. Steps that only
+ * exercise their own arg-resolution + step-list-assembly don't read
+ * any ctx field; the runner needs an object-shaped ctx but no surface
+ * beyond that.
+ *
+ * Tests that actually use ctx fields (db, query, appendEvent, etc.)
+ * belong in pipeline-handler.integration.ts against the real stack.
+ */
+export function buildMinimalCtx(): HandlerContext {
+  return {} as HandlerContext;
+}

package/src/engine/__tests__/build-target.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "vitest";
+import { buildTarget, type TreeActionDef } from "../index";
+
+// createTreeActionsStub — Test-Helper für Phase-0-Stub-Features. Das
+// `const`-Generic-Modifier forciert Literal-Inference, sodass die
+// Action-Namen als string-literal-Union ankommen (statt zu `string`
+// widening). In V.1.1 wird der Helper überflüssig: echte defineFeature-
+// Outputs haben dieselbe Shape und Tests konsumieren die direkt.
+function createTreeActionsStub<const TActions extends Record<string, TreeActionDef>>(spec: {
+  readonly id: string;
+  readonly treeActions: TActions;
+}): { readonly id: string; readonly treeActions: TActions } {
+  return Object.freeze({ id: spec.id, treeActions: spec.treeActions });
+}
+
+const textContentStub = createTreeActionsStub({
+  id: "text-content",
+  treeActions: {
+    edit: { args: { slug: "" as string } },
+    create: { args: { folder: "" as string } },
+    list: {},
+  },
+});
+
+describe("buildTarget — NoArgs-Action", () => {
+  test("erzeugt TargetRef ohne args-Feld", () => {
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect(ref).toEqual({ featureId: "text-content", action: "list" });
+    expect("args" in ref).toBe(false);
+  });
+
+  test("output ist frozen (immutable)", () => {
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect(Object.isFrozen(ref)).toBe(true);
+  });
+});
+
+describe("buildTarget — WithArgs-Action", () => {
+  test("erzeugt TargetRef mit args", () => {
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(ref).toEqual({
+      featureId: "text-content",
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+  });
+
+  test("args sind frozen — Mutation am Input-Objekt schlägt nicht durch", () => {
+    const inputArgs = { slug: "imprint" };
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: inputArgs,
+    });
+    inputArgs.slug = "mutated";
+    expect(ref.args).toEqual({ slug: "imprint" });
+    expect(Object.isFrozen(ref.args)).toBe(true);
+  });
+
+  test("verschiedene Actions haben unterschiedliche Arg-Shapes", () => {
+    const editRef = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    const createRef = buildTarget({
+      target: textContentStub,
+      action: "create",
+      args: { folder: "/marketing" },
+    });
+    expect(editRef.args).toEqual({ slug: "imprint" });
+    expect(createRef.args).toEqual({ folder: "/marketing" });
+  });
+});
+
+describe("buildTarget — Compile-Time-Safety (verified via @ts-expect-error)", () => {
+  // Jeder Test paart ein @ts-expect-error-Block (compile-time-validation
+  // via TypeScript) mit einem runtime-expect über den korrespondierenden
+  // Happy-Path. Doppelt-Coverage: Compiler prüft Rejection, vitest prüft
+  // dass die korrekte Form bei valid input das richtige Ergebnis liefert.
+  // Memory `[Keine Fake-Tests]` — Tests müssen runtime-Verhalten prüfen,
+  // nicht nur Compile-Time (Fake-Test-Guard).
+
+  test("unbekannte action wird vom Compiler abgelehnt", () => {
+    // @ts-expect-error — "delet" ist keine Action von textContentStub
+    buildTarget({ target: textContentStub, action: "delet" });
+    // Runtime: bekannte Action liefert valid TargetRef
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect(ref.action).toBe("list");
+  });
+
+  test("falsche args-shape wird vom Compiler abgelehnt", () => {
+    // @ts-expect-error — slug muss string sein, nicht number
+    buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: 42 },
+    });
+    // Runtime: korrekt-typed args liefern valid TargetRef
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(ref.args).toEqual({ slug: "imprint" });
+  });
+
+  test("args bei NoArgs-Action wird vom Compiler abgelehnt", () => {
+    buildTarget({
+      target: textContentStub,
+      action: "list",
+      // @ts-expect-error — list hat keine args, args-Feld nicht erlaubt
+      args: { x: 1 },
+    });
+    // Runtime: NoArgs-Action ohne args-Feld liefert valid TargetRef
+    const ref = buildTarget({ target: textContentStub, action: "list" });
+    expect("args" in ref).toBe(false);
+  });
+
+  test("fehlende args bei WithArgs-Action wird vom Compiler abgelehnt", () => {
+    // @ts-expect-error — edit braucht args, fehlt
+    buildTarget({ target: textContentStub, action: "edit" });
+    // Runtime: WithArgs-Action mit args liefert valid TargetRef
+    const ref = buildTarget({
+      target: textContentStub,
+      action: "edit",
+      args: { slug: "imprint" },
+    });
+    expect(ref.args).toBeDefined();
+  });
+});