@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

package/src/pipeline/lifecycle-pipeline.ts

@@ -13,6 +13,7 @@ import type {
   SaveContext,
 } from "../engine/types";
 import { HookPhases } from "../engine/types";
+import { createFallbackLogger } from "../logging/utils";
 import { getFallbackTracer, type Tracer } from "../observability";
 import type { EventDedup } from "./event-dedup";
 
@@ -253,14 +254,9 @@ export function createLifecycleHooks(
     }
 
     if (errors.length > 0) {
-      const log = opts.context.log;
+      const logError = createFallbackLogger("lifecycle", opts.context.log);
       const msg = `${opts.phaseLabel} errors for ${opts.handlerName}`;
-      const details = errors.map((e) => `${e.name}: ${e.error}`);
-      if (log) {
-        log.error(msg, { errors: details });
-      } else {
-        console.error(`[lifecycle] ${msg}:`, details);
-      }
+      logError.error(msg, { details: errors.map((e) => `${e.name}: ${e.error}`) });
     }
   }
 
@@ -397,11 +393,9 @@ export function createLifecycleHooks(
     // skip: all batch hooks succeeded, nothing to log
     if (failures.length === 0) return;
 
-    const log = opts.context.log;
+    const logError = createFallbackLogger("lifecycle", opts.context.log);
     const msg = `${opts.phaseLabel} errors`;
-    const details = failures.map((f) => `${f.name}: ${f.outcome.reason}`);
-    if (log) log.error(msg, { errors: details });
-    else console.error(`[lifecycle] ${msg}:`, details);
+    logError.error(msg, { details: failures.map((f) => `${f.name}: ${f.outcome.reason}`) });
   }
 }
 
@@ -422,6 +416,6 @@ export function buildEventId(handlerName: string, payload: unknown, phase: strin
   if (typeof rawId !== "string" && typeof rawId !== "number") return null;
   if (rawId === 0 || rawId === "") return null;
   const data = p["data"] as Record<string, unknown> | undefined; // @cast-boundary engine-payload
-  const version = data?.["version"] as number | undefined;
+  const version = data?.["version"] as number | undefined; // @cast-boundary engine-payload
   return `${handlerName}:${rawId}:${version ?? 0}:${phase}`;
 }

package/src/pipeline/msp-rebuild.ts

@@ -67,7 +67,7 @@ function createRebuildCtx(
   };
   return {
     appendEvent: refuseAppend as MultiStreamApplyContext["appendEvent"], // @cast-boundary engine-bridge
-    appendEventUnsafe: refuseAppend,
+    unsafeAppendEvent: refuseAppend,
     loadAggregate: async (aggregateId, options) => {
       const events = options?.asOf
         ? await loadAggregateAsOf(db, aggregateId, tenantId, options.asOf)
@@ -142,7 +142,7 @@ export async function rebuildMultiStreamProjection(
       // msp.table is narrowed by the upfront guard; the assertion here is
       // for TS inside the async closure (narrowing doesn't cross the
       // transaction boundary).
-      const tableName = getTableName(msp.table as NonNullable<typeof msp.table>);
+      const tableName = getTableName(msp.table as NonNullable<typeof msp.table>); // @cast-boundary db-operator
       await tx.execute(sql.raw(`TRUNCATE TABLE ${quoteIdent(tableName)}`));
 
       const subscribedTypes = Object.keys(msp.apply);
@@ -151,7 +151,7 @@ export async function rebuildMultiStreamProjection(
           .select()
           .from(eventsTable)
           .where(inArray(eventsTable.type, subscribedTypes))
-          .orderBy(asc(eventsTable.id))) as ReadonlyArray<typeof eventsTable.$inferSelect>;
+          .orderBy(asc(eventsTable.id))) as ReadonlyArray<typeof eventsTable.$inferSelect>; // @cast-boundary db-row
 
         const upcasters = registry.getEventUpcasters();
         for (const row of events) {
@@ -170,11 +170,11 @@ export async function rebuildMultiStreamProjection(
           };
           const storedEvent = await upcastStoredEvent(raw, upcasters, {
             db: tx,
-            tenantId: row.tenantId as TenantId,
+            tenantId: row.tenantId as TenantId, // @cast-boundary db-row
           });
           const applyFn = msp.apply[row.type];
           if (!applyFn) continue;
-          const rebuildCtx = createRebuildCtx(registry, tx, row.tenantId as TenantId);
+          const rebuildCtx = createRebuildCtx(registry, tx, row.tenantId as TenantId); // @cast-boundary db-row
           await applyFn(storedEvent, tx, rebuildCtx);
           eventsProcessed++;
           lastProcessedEventId = row.id;

package/src/pipeline/multi-stream-apply-context.ts

@@ -2,10 +2,10 @@ import type { DbRunner } from "../db/connection";
 import type {
   AppendEventArgs,
   AppendEventFn,
-  AppendEventUnsafeFn,
   KumikoEventTypeMap,
   Registry,
   TenantId,
+  UnsafeAppendEventFn,
 } from "../engine/types";
 import { loadAggregate, loadAggregateAsOf, type StoredEvent } from "../event-store/event-store";
 import { upcastStoredEvents } from "../event-store/upcaster";
@@ -20,7 +20,7 @@ import { appendDomainEventCore } from "./append-event-core";
 //
 // TMap propagates the strict event-type-map (see HandlerContext). Default
 // matches the global KumikoEventTypeMap; runtime-pluggable callers route
-// through appendEventUnsafe.
+// through unsafeAppendEvent.
 export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
   // Append a domain event onto an aggregate stream in the CURRENT tx.
   // Schema-validated, archive-guarded, stream-version derived. Metadata
@@ -31,7 +31,7 @@ export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> =
   readonly appendEvent: AppendEventFn<TMap>;
   // Escape hatch for runtime-pluggable events without compile-time
   // augmentation. Same runtime semantics; type-surface is `payload: unknown`.
-  readonly appendEventUnsafe: AppendEventUnsafeFn;
+  readonly unsafeAppendEvent: UnsafeAppendEventFn;
   // Read an aggregate stream — useful when a saga needs to inspect the
   // current state of a different aggregate before deciding what to emit.
   readonly loadAggregate: (
@@ -74,7 +74,6 @@ export function createMultiStreamApplyContext(
 ): MultiStreamApplyContext {
   return {
     ...(deps.files ? { files: deps.files } : {}),
-    // @cast-boundary engine-bridge — concrete impl conforms to AppendEventFn overload
     appendEvent: (async (args: AppendEventArgs) => {
       await appendDomainEventCore(
         {
@@ -87,15 +86,15 @@ export function createMultiStreamApplyContext(
         },
         args,
       );
-    }) as AppendEventFn,
-    appendEventUnsafe: async (args) => {
+    }) as AppendEventFn, // @cast-boundary engine-bridge
+    unsafeAppendEvent: async (args) => {
       await appendDomainEventCore(
         {
           registry: deps.registry,
           db: deps.db,
           tenantId: deps.tenantId,
           userId: deps.userId,
-          callSiteLabel: "MSP-apply ctx.appendEventUnsafe",
+          callSiteLabel: "MSP-apply ctx.unsafeAppendEvent",
           ...(deps.callerFeature && { callerFeature: deps.callerFeature }),
         },
         args,

package/src/pipeline/projection-rebuild.ts

@@ -127,7 +127,7 @@ export async function rebuildProjection(
               subscribed,
             )}`,
           )
-          .orderBy(asc(eventsTable.id))) as ReadonlyArray<typeof eventsTable.$inferSelect>;
+          .orderBy(asc(eventsTable.id))) as ReadonlyArray<typeof eventsTable.$inferSelect>; // @cast-boundary db-row
 
         // Upcasters run at read time: older stored payloads get walked
         // through the registered r.eventMigration chain until their shape
@@ -151,7 +151,7 @@ export async function rebuildProjection(
           };
           const storedEvent = await upcastStoredEvent(raw, upcasters, {
             db: tx,
-            tenantId: row.tenantId as TenantId,
+            tenantId: row.tenantId as TenantId, // @cast-boundary db-row
           });
           const applyFn = projection.apply[row.type];
           // skip: apply-key validation ensures every subscribed type has a

package/src/pipeline/projection-state.ts

@@ -49,18 +49,6 @@ export const ProjectionStatuses = {
 } as const;
 export type ProjectionStatus = (typeof ProjectionStatuses)[keyof typeof ProjectionStatuses];
 
-/**
- * @deprecated Use `ProjectionStatuses` (object form) or the `ProjectionStatus`
- * union type. Tuple alias kept for back-compat with callers that relied on
- * the array form (`z.enum(...)`, runtime iteration) — scheduled for removal
- * after downstream migration.
- */
-export const PROJECTION_STATUSES = [
-  "idle",
-  "rebuilding",
-  "failed",
-] as const satisfies readonly ProjectionStatus[];
-
 // Idempotent table bootstrap. Called by setupTestStack (and createApp once
 // that wires it up) — same pattern as createEventsTable. If the table is
 // already there (second stack in same test DB, production boot after

package/src/rate-limit/__tests__/resolver.integration.ts

@@ -1,7 +1,11 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
 import { RateLimitError } from "../../errors";
 import { createTestRedis, type TestRedis } from "../../stack";
-import { createRateLimitResolver, type RateLimitResolver } from "../resolver";
+import {
+  createRateLimitResolver,
+  type RateLimitDecision,
+  type RateLimitResolver,
+} from "../resolver";
 
 let testRedis: TestRedis;
 let resolver: RateLimitResolver;
@@ -32,7 +36,7 @@ beforeEach(async () => {
 describe("createRateLimitResolver — token bucket basics", () => {
   test("first N requests within limit are allowed, N+1 is rejected", async () => {
     const config = { limit: 5, windowSeconds: 60 };
-    const decisions = [];
+    const decisions: RateLimitDecision[] = [];
     for (let i = 0; i < 5; i++) {
       decisions.push(await resolver.check("user:42", config));
     }
@@ -66,7 +70,7 @@ describe("createRateLimitResolver — token bucket basics", () => {
 
     // Advance 5s = window/2 → ~5 tokens refilled
     mockNowMs += 5000;
-    const decisions = [];
+    const decisions: RateLimitDecision[] = [];
     for (let i = 0; i < 5; i++) {
       decisions.push(await resolver.check("refill:user", config));
     }
@@ -84,7 +88,7 @@ describe("createRateLimitResolver — token bucket basics", () => {
     // Advance 10× the window → bucket would overflow without the cap.
     mockNowMs += 10 * 10 * 1000;
 
-    const decisions = [];
+    const decisions: RateLimitDecision[] = [];
     for (let i = 0; i < 5; i++) {
       decisions.push(await resolver.check("idle:user", config));
     }

package/src/rate-limit/resolver.ts

@@ -185,7 +185,7 @@ function ensureCommand(redis: Redis): CommandClient {
     });
     REGISTERED.add(redis);
   }
-  return redis as CommandClient;
+  return redis as CommandClient; // @cast-boundary engine-bridge
 }
 
 export function createRateLimitResolver(opts: RateLimitResolverOptions): RateLimitResolver {

package/src/search/in-memory-adapter.ts

@@ -1,4 +1,4 @@
-import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { EntityId, TenantId } from "../engine/types/identifiers";
 import type { SearchAdapter, SearchAdapterConfig, SearchResult } from "./types";
 
 type StoredDoc = {

package/src/search/meilisearch-adapter.ts

@@ -1,5 +1,5 @@
-import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Meilisearch } from "meilisearch";
+import type { EntityId, TenantId } from "../engine/types/identifiers";
 import type { SearchAdapter, SearchResult } from "./types";
 
 export type MeilisearchAdapterOptions = {
@@ -92,8 +92,8 @@ export function createMeilisearchAdapter(options: MeilisearchAdapterOptions): Se
 
       return results.hits.map(
         (hit: Record<string, unknown>): SearchResult => ({
-          entityType: hit["_type"] as string,
-          entityId: hit["_entityId"] as EntityId,
+          entityType: hit["_type"] as string, // @cast-boundary engine-bridge
+          entityId: hit["_entityId"] as EntityId, // @cast-boundary engine-bridge
         }),
       );
     },

package/src/search/types.ts

@@ -1,4 +1,4 @@
-import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { EntityId, TenantId } from "../engine/types/identifiers";
 
 export type SearchAdapterConfig = {
   searchableFields: readonly string[];

package/src/secrets/leak-guard.ts

@@ -80,8 +80,8 @@ export function assertNoSecretLeak(value: unknown, path = "$", depth = 0): void
     return;
   }
 
-  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-    // @cast-boundary recursive-walk
+  const obj = value as Record<string, unknown>; // @cast-boundary recursive-walk
+  for (const [k, v] of Object.entries(obj)) {
     assertNoSecretLeak(v, `${path}.${k}`, depth + 1);
   }
 }

package/src/stack/request-helper.ts

@@ -112,7 +112,9 @@ export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
       const res = await writeRaw(type, payload, user, requestId);
       // wire-body shape direkt nach JSON.parse — Caller-Code prüft danach
       // selber ob isSuccess/error/data tatsächlich da sind.
-      const body = (await res.json()) as {
+      const rawBody = await res.json();
+      const body = rawBody as {
+        // @cast-boundary engine-bridge
         isSuccess?: boolean;
         data?: unknown;
         error?: { code?: string } | string;
@@ -126,7 +128,7 @@ export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
           (typeof body.error === "string" ? body.error : "unknown");
         throw new Error(`Expected write "${type}" to succeed but got error: ${code}`);
       }
-      return body.data as T;
+      return body.data as T; // @cast-boundary engine-bridge
     },
 
     async writeErr(
@@ -135,7 +137,9 @@ export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
       user: SessionUser,
     ): Promise<import("../errors").WriteErrorInfo> {
       const res = await writeRaw(type, payload, user);
-      const body = (await res.json()) as {
+      const rawErrorBody = await res.json();
+      const body = rawErrorBody as {
+        // @cast-boundary engine-bridge
         isSuccess?: boolean;
         error?: Omit<import("../errors").WriteErrorInfo, "httpStatus">;
       };
@@ -156,8 +160,8 @@ export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
 
     async queryOk<T = unknown>(type: string, payload: unknown, user: SessionUser): Promise<T> {
       const res = await queryRaw(type, payload, user);
-      const body = (await res.json()) as { data: unknown };
-      return body.data as T;
+      const body = (await res.json()) as { data: unknown }; // @cast-boundary engine-bridge
+      return body.data as T; // @cast-boundary engine-bridge
     },
 
     async writeWithHeaders(type, payload, user, extraHeaders) {

package/src/stack/test-stack.ts

@@ -209,7 +209,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     const { getTableName } = await import("drizzle-orm");
     const missing: Record<string, unknown> = {};
     for (const [key, tbl] of Object.entries(projectionTables)) {
-      const physical = getTableName(tbl as Parameters<typeof getTableName>[0]);
+      const physical = getTableName(tbl as Parameters<typeof getTableName>[0]); // @cast-boundary drizzle-bridge
       if (await tableExists(testDb.db, `public.${physical}`)) continue;
       missing[key] = tbl;
     }

package/src/testing/handler-context.ts

@@ -45,7 +45,7 @@ export function bridgeStub(opts?: {
   | "write"
   | "writeAs"
   | "appendEvent"
-  | "appendEventUnsafe"
+  | "unsafeAppendEvent"
   | "fetchForWriting"
   | "loadAggregate"
   | "archiveStream"
@@ -68,12 +68,12 @@ export function bridgeStub(opts?: {
   // SessionUser hier und bekommt ihn am ctx zurück.
   const stubUser: SessionUser = opts?.user ?? {
     id: "00000000-0000-0000-0000-000000000000",
-    tenantId: "00000000-0000-0000-0000-000000000000" as SessionUser["tenantId"],
+    tenantId: "00000000-0000-0000-0000-000000000000" as SessionUser["tenantId"], // @cast-boundary engine-bridge
     roles: ["all"],
   };
   return {
     user: stubUser,
-    query: notAvailable("query") as HandlerContext["query"],
+    query: notAvailable("query") as HandlerContext["query"], // @cast-boundary engine-bridge
     queryAs: notAvailable("queryAs") as unknown as (
       user: SessionUser,
       qn: string,
@@ -89,7 +89,7 @@ export function bridgeStub(opts?: {
       payload: unknown,
     ) => Promise<WriteResult>,
     appendEvent: notAvailable("appendEvent") as unknown as (args: AppendEventArgs) => Promise<void>,
-    appendEventUnsafe: notAvailable("appendEventUnsafe") as unknown as (
+    unsafeAppendEvent: notAvailable("unsafeAppendEvent") as unknown as (
       args: AppendEventArgs,
     ) => Promise<void>,
     fetchForWriting: notAvailable("fetchForWriting") as unknown as (

package/src/testing/http-cookies.ts

@@ -22,7 +22,7 @@ export type ParsedSetCookie = {
 // is acceptable here because tests that set multiple cookies run on a
 // runtime that supports getSetCookie.
 export function getSetCookies(res: Response): Map<string, ParsedSetCookie> {
-  const getter = (res.headers as { getSetCookie?: () => string[] }).getSetCookie;
+  const getter = (res.headers as { getSetCookie?: () => string[] }).getSetCookie; // @cast-boundary engine-bridge
   const raws = getter ? getter.call(res.headers) : [res.headers.get("set-cookie") ?? ""];
   const out = new Map<string, ParsedSetCookie>();
   for (const raw of raws) {

package/src/time/tz-context.ts

@@ -11,9 +11,8 @@
 // kommt in einer späteren Iteration, wenn alle existing usages migriert sind.
 //
 // `tenant` + `user` sind die TZ-Defaults für den aktuellen Request. Aktueller
-// Stand (Iteration 4): beide default auf "UTC" — sobald tenant.timezone +
+// Stand: beide default auf "UTC" — sobald tenant.timezone +
 // user.timezone Felder existieren, lese ich sie aus dem Request-Context.
-// TODO(Iteration 6): aus tenant entity / user profile lesen.
 
 import { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 

package/src/ui-types/index.ts

@@ -55,10 +55,14 @@ export type {
   FieldRenderer,
   ListColumnSpec,
   PlatformComponent,
+  RowAction,
+  RowActionNavigate,
+  RowActionWriteHandler,
   ScreenDefinition,
   ScreenFilter,
   ScreenFilterOp,
   ScreenSlots,
+  ToolbarAction,
 } from "../engine/types/screen";
 export { normalizeEditField, normalizeListColumn } from "../engine/types/screen";
 export type { WorkspaceDefinition } from "../engine/types/workspace";