@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

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();
+  });
+});