@cosmicdrift/kumiko-bundled-features 0.2.3 → 0.3.0

package/src/step-dispatcher/webhook-runner.ts

@@ -0,0 +1,67 @@
+// Webhook execution logic — separated from feature.ts so tests can stub
+// the fetch without touching the MSP wiring.
+
+import { z } from "zod";
+
+export const webhookSpecSchema = z.object({
+  url: z.string(),
+  method: z.enum(["POST", "PUT", "PATCH"]),
+  headers: z.record(z.string(), z.string()),
+  body: z.unknown().optional(),
+  auth: z
+    .union([
+      z.object({ kind: z.literal("bearer"), secretRef: z.string() }),
+      z.object({ kind: z.literal("header"), name: z.string(), secretRef: z.string() }),
+    ])
+    .optional(),
+});
+
+export type WebhookSpec = z.infer<typeof webhookSpecSchema>;
+
+export type WebhookDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+// Resolves a secretRef via the test-injectable secret-store. Default
+// implementation reads from process.env at the prefix WEBHOOK_SECRET_.
+// Tests pass a custom resolver via setWebhookSecretResolver.
+let secretResolver: (ref: string) => string | undefined = (ref) =>
+  process.env[`WEBHOOK_SECRET_${ref}`];
+
+export function setWebhookSecretResolver(fn: (ref: string) => string | undefined): void {
+  secretResolver = fn;
+}
+
+let fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis);
+
+export function setWebhookFetch(fn: typeof fetch): void {
+  fetchImpl = fn;
+}
+
+export async function performWebhookDispatch(spec: WebhookSpec): Promise<WebhookDispatchResult> {
+  const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
+  if (spec.auth) {
+    const secret = secretResolver(spec.auth.secretRef);
+    if (!secret) {
+      return { ok: false, error: `secret "${spec.auth.secretRef}" not configured` };
+    }
+    if (spec.auth.kind === "bearer") {
+      headers["authorization"] = `Bearer ${secret}`;
+    } else {
+      headers[spec.auth.name] = secret;
+    }
+  }
+  try {
+    const res = await fetchImpl(spec.url, {
+      method: spec.method,
+      headers,
+      body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
+    });
+    if (!res.ok) {
+      return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/subscription-mollie/plugin-methods.ts

@@ -66,7 +66,7 @@ export function createMollieCheckoutSession(
         tenantId: options.tenantId,
         priceId: options.priceId,
       },
-    }) as Promise<Payment>)) satisfies Payment;
+    }) as Promise<Payment>)) satisfies Payment; // @cast-boundary engine-bridge
 
     const checkoutHref = payment.getCheckoutUrl();
     if (!checkoutHref) {

package/src/subscription-mollie/verify-webhook.ts

@@ -102,7 +102,7 @@ export function verifyAndParseMollieWebhook(
       return null;
     }
 
-    const metadata = (subscription.metadata as Record<string, string> | null) ?? {};
+    const metadata = (subscription.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
     const tenantId = metadata["tenantId"];
     if (!tenantId || tenantId.length === 0) return null;
     const priceId = metadata["priceId"];
@@ -153,7 +153,7 @@ async function ensureSubscriptionForMandate(
 ): Promise<MollieSubscription | null> {
   const customerId = payment.customerId;
   if (!customerId) return null;
-  const paymentMetadata = (payment.metadata as Record<string, string> | null) ?? {};
+  const paymentMetadata = (payment.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
   const tenantId = paymentMetadata["tenantId"];
   const priceId = paymentMetadata["priceId"];
   if (!tenantId || !priceId) return null;
@@ -163,7 +163,7 @@ async function ensureSubscriptionForMandate(
   const existing = await client.customerSubscriptions.list(customerId);
   const matchingExisting = existing.find(
     (sub) =>
-      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId &&
+      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId && // @cast-boundary engine-bridge
       (sub.status === "active" || sub.status === "pending"),
   );
   if (matchingExisting) return matchingExisting;
@@ -185,8 +185,12 @@ export function extractMollieId(rawBody: string, headers: Record<string, string>
   const contentType = headers["content-type"] ?? "";
   if (contentType.includes("application/json")) {
     try {
-      const parsed = JSON.parse(rawBody) as { id?: unknown };
-      return typeof parsed.id === "string" ? parsed.id : null;
+      const parsed: unknown = JSON.parse(rawBody);
+      const id =
+        typeof parsed === "object" && parsed !== null && "id" in parsed
+          ? (parsed as Record<string, unknown>)["id"] // @cast-boundary engine-payload
+          : undefined;
+      return typeof id === "string" ? id : null;
     } catch {
       return null;
     }

package/src/subscription-stripe/verify-webhook.ts

@@ -203,15 +203,15 @@ async function extractSubscriptionFromEvent(
     case StripeEventTypes.customerSubscriptionCreated:
     case StripeEventTypes.customerSubscriptionUpdated:
     case StripeEventTypes.customerSubscriptionDeleted:
-      return event.data.object as Stripe.Subscription;
+      return event.data.object as Stripe.Subscription; // @cast-boundary engine-bridge
     case StripeEventTypes.invoicePaid:
     case StripeEventTypes.invoicePaymentFailed: {
       // Lazy-fetch der subscription. invoice.subscription ist eine
       // string-id (Stripe-Webhooks expanden nicht auto). Wir holen das
       // full subscription-Object damit der downstream-mapping
       // (status, tier via priceId, period-end) konsistent funktioniert.
-      const invoice = event.data.object as Stripe.Invoice;
-      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null })
+      const invoice = event.data.object as Stripe.Invoice; // @cast-boundary engine-bridge
+      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null }) // @cast-boundary engine-payload
         .subscription;
       if (!subRef) {
         // Invoice ohne subscription-reference (= one-shot-invoice, nicht

package/src/tenant/handlers/active-tenant-ids.query.ts

@@ -14,6 +14,6 @@ export const activeTenantIdsQuery = defineQueryHandler({
       .from(tenantTable)
       .where(eq(tenantTable["isEnabled"], true));
 
-    return rows.map((row) => (row as DbRow)["id"] as number);
+    return rows.map((row) => (row as DbRow)["id"] as number); // @cast-boundary db-row
   },
 });

package/src/tenant/handlers/cancel-invitation.write.ts

@@ -61,7 +61,7 @@ export const cancelInvitationWrite = defineWriteHandler({
     const updateResult = await executor.update(
       {
         id: event.payload.invitationId,
-        version: invitation["version"] as number,
+        version: invitation["version"] as number, // @cast-boundary db-row
         changes: { status: INVITATION_STATUS.cancelled },
       },
       event.user,

package/src/tenant/handlers/remove-member.write.ts

@@ -31,7 +31,7 @@ export const removeMemberWrite = defineWriteHandler({
     }
 
     const result = await executor.delete(
-      { id: (existing as DbRow)["id"] as string },
+      { id: (existing as DbRow)["id"] as string }, // @cast-boundary db-row
       event.user,
       db,
     );

package/src/tenant/handlers/resolve-user-ids.query.ts

@@ -27,7 +27,7 @@ export const resolveUserIdsQuery = defineQueryHandler({
         .select({ userId: tenantMembershipsTable.userId })
         .from(tenantMembershipsTable)
         .where(eq(tenantMembershipsTable.tenantId, tenantId));
-      return rows.map((r) => r["userId"] as number);
+      return rows.map((r) => r["userId"] as number); // @cast-boundary db-row
     }
 
     if (userId !== undefined) {

package/src/tenant/handlers/update-member-roles.write.ts

@@ -39,11 +39,11 @@ export const updateMemberRolesWrite = defineWriteHandler({
     // between this read and append) surfaces as version_conflict rather than
     // silent overwrite. Per-membership parallelism is rare; if it happens,
     // the client retries on the error.
-    const row = existing as DbRow;
+    const row = existing as DbRow; // @cast-boundary generic-record
     const result = await executor.update(
       {
-        id: row["id"] as string,
-        version: row["version"] as number,
+        id: row["id"] as string, // @cast-boundary db-row
+        version: row["version"] as number, // @cast-boundary db-row
         changes: { roles: JSON.stringify(event.payload.roles) },
       },
       event.user,

package/src/text-content/constants.ts

@@ -1,3 +1,4 @@
+// @runtime client
 // Feature name
 export const TEXT_CONTENT_FEATURE = "text-content" as const;
 
@@ -9,6 +10,7 @@ export const TextContentHandlers = {
 // Qualified query handler names (QN format: scope:type:name)
 export const TextContentQueries = {
   bySlug: "text-content:query:by-slug",
+  byTenant: "text-content:query:by-tenant",
 } as const;
 
 // Error codes

package/src/text-content/feature.ts

@@ -1,5 +1,6 @@
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { bySlugQuery } from "./handlers/by-slug.query";
+import { byTenantQuery } from "./handlers/by-tenant.query";
 import { setWrite } from "./handlers/set.write";
 import { textBlockEntity } from "./table";
 
@@ -11,8 +12,16 @@ import { textBlockEntity } from "./table";
 //
 // Opt-in: wer keine statischen Texte braucht (interne Tools), aktiviert
 // das Feature gar nicht. Wer es aktiviert, hat sofort CRUD + by-slug-
-// query — Routes/Render kommen pro Use-Case (legal-pages, etc.).
-export function createTextContentFeature(): FeatureDefinition {
+// query + by-tenant-list-query — Routes/Render kommen pro Use-Case
+// (legal-pages, Visual-Tree, etc.).
+//
+// **Visual-Tree-Integration (V.1.2)**: r.treeActions deklariert die
+// Edit-Actions für Cross-Feature-Linking via buildTarget. Der Handle
+// wird via setup-export propagiert (Memory `[EventDef-Exports-Pattern]`),
+// sodass andere Features compile-time-typed Cross-Feature-Edits triggern
+// können — siehe legal-pages's TreeProvider der text-content:edit als
+// Target nutzt. Der Client-side TreeProvider lebt in `web/client-plugin.ts`.
+export function createTextContentFeature() {
   return defineFeature("text-content", (r) => {
     r.entity("text-block", textBlockEntity);
 
@@ -22,8 +31,15 @@ export function createTextContentFeature(): FeatureDefinition {
 
     const queries = {
       bySlug: r.queryHandler(bySlugQuery),
+      byTenant: r.queryHandler(byTenantQuery),
     };
 
-    return { handlers, queries };
+    const treeHandle = r.treeActions({
+      edit: { args: { slug: "" as string, lang: "" as string } },
+      list: {},
+      create: { args: { folder: "" as string } },
+    });
+
+    return { handlers, queries, treeHandle };
   });
 }

package/src/text-content/handlers/by-tenant.query.ts

@@ -0,0 +1,56 @@
+import { castTenantRows } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { type TextBlockRow, textBlocksTable } from "../table";
+
+// Public-Read aller Text-Blocks für einen Tenant. Use-Case: Visual-Tree-
+// Provider lädt die Slug-Liste zur Sidebar-Render. Anonymous: explizit
+// in roles damit no-JWT-Visitors auch lesen können (Marketing-Sidebar
+// auf Public-Pages). Tenant-Scope kommt aus query.user.tenantId; optional
+// `tenantIdOverride` (SystemAdmin-only) — symmetrisch zu by-slug.query.
+//
+// **Listing statt single-row**: anders als by-slug returnt das hier
+// `{ blocks: [...] }` mit allen Slugs des Tenants. Pro Slug nur die
+// Summary-Felder (kein full body — den lädt der Editor on-demand via
+// by-slug). Hält die Sidebar-Payload klein bei vielen Slugs.
+export type TextBlockSummary = {
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly updatedAt: Date;
+};
+
+export const byTenantQuery = defineQueryHandler({
+  name: "by-tenant",
+  schema: z.object({
+    /** Optional cross-tenant read — nur für SystemAdmin. Symmetrisch
+     *  zur by-slug.query und set.write Override-Logik. */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const override = query.payload.tenantIdOverride;
+    if (override !== undefined && !query.user.roles.includes("SystemAdmin")) {
+      throw new AccessDeniedError({
+        i18nKey: "textContent.errors.tenantOverrideRequiresSystemAdmin",
+        details: { reason: "tenant_override_requires_system_admin" },
+      });
+    }
+    const tenantId = override ?? query.user.tenantId;
+    const rows = castTenantRows<TextBlockRow>(
+      await ctx.db.select().from(textBlocksTable).where(eq(textBlocksTable["tenantId"], tenantId)),
+    );
+    return {
+      blocks: rows.map((row) => ({
+        slug: row.slug,
+        lang: row.lang,
+        title: row.title,
+        body: row.body,
+        updatedAt: row.updatedAt,
+      })),
+    };
+  },
+});

package/src/text-content/handlers/set.write.ts

@@ -68,7 +68,7 @@ export const setWrite = defineWriteHandler({
     // Symmetrisch zu seedTextBlock, das TestUsers.systemAdmin (tenantId =
     // SYSTEM_TENANT) als by verwendet.
     const executorUser =
-      override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user;
+      override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user; // @cast-boundary engine-bridge
 
     const existing = await fetchOne<TextBlockRow>(
       db,

package/src/text-content/web/client-plugin.ts

@@ -0,0 +1,113 @@
+// @runtime client
+// Client-Feature-Factory für text-content Visual-Tree. Wird vom App-Code
+// in createKumikoApp({ clientFeatures: [textContentClient()] }) eingehängt
+// und liefert den treeProvider der Text-Blocks aus der by-tenant Query
+// lädt, nach Slug-Prefix gruppiert und als TreeNode[] emitted.
+//
+// **Slug-Gruppierung**: Slugs der Form `<prefix>:<rest>` oder `<prefix>/<rest>`
+// werden unter einem `<prefix>`-Container-Knoten gruppiert. Slugs ohne
+// Trenner landen als Top-Level-Knoten. Beispiele:
+//   - "page:index:hero.title" → folder "page", label "index:hero.title"
+//   - "imprint"               → root-node, label "imprint"
+// V.1.3+ kann mehrstufige Hierarchien einführen wenn realer Bedarf zeigt.
+//
+// **State**: TreeNode.state = "filled" wenn body gesetzt ist, sonst
+// "stub" (hellgrau, Designer-Hinweis dass Slug existiert aber leer ist).
+//
+// **Fetch statt Subscribe**: V.1.1 ist Fetch-once beim Mount. Unsubscribe
+// ist no-op. V.1.3+ kann SSE-driven Re-Emit einbauen wenn text-block-
+// updated-Events propagiert werden.
+
+import type { TreeChildrenSubscribe, TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { TextContentQueries } from "../constants";
+
+type BlockSummary = {
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly updatedAt: string;
+};
+
+type ByTenantResponse = {
+  readonly data: { readonly blocks: readonly BlockSummary[] };
+};
+
+// Folder-Name = alles vor dem ersten ":" oder "/", oder undefined wenn
+// der Slug keinen Trenner enthält (dann landet er als Root-Node).
+function getFolderName(slug: string): string | undefined {
+  const sepIdx = slug.search(/[:/]/);
+  if (sepIdx === -1) return undefined;
+  return slug.slice(0, sepIdx);
+}
+
+function groupBlocksBySlugPrefix(blocks: readonly BlockSummary[]): readonly TreeNode[] {
+  const rootNodes: TreeNode[] = [];
+  const folders = new Map<string, TreeNode[]>();
+
+  for (const block of blocks) {
+    const node: TreeNode = {
+      label: block.title || block.slug,
+      target: {
+        featureId: "text-content",
+        action: "edit",
+        args: { slug: block.slug, lang: block.lang },
+      },
+      state: block.body ? "filled" : "stub",
+    };
+
+    const folderName = getFolderName(block.slug);
+    if (folderName === undefined) {
+      rootNodes.push(node);
+    } else {
+      const existing = folders.get(folderName) ?? [];
+      existing.push(node);
+      folders.set(folderName, existing);
+    }
+  }
+
+  for (const [name, children] of folders) {
+    rootNodes.push({
+      label: name,
+      icon: "folder",
+      state: "filled",
+      children,
+    });
+  }
+
+  return rootNodes;
+}
+
+const treeProvider: TreeChildrenSubscribe = (_ctx) => (emit) => {
+  fetch("/api/query", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      type: TextContentQueries.byTenant,
+      payload: {},
+    }),
+  })
+    .then((r) => r.json())
+    .then((data: ByTenantResponse) => {
+      const nodes = groupBlocksBySlugPrefix(data.data.blocks);
+      emit(nodes);
+    })
+    .catch(() => {
+      // V.1.3+ TODO: state="error"-Knoten + Reload-Action statt empty.
+      emit([]);
+    });
+  return () => {};
+};
+
+export function textContentClient(): ClientFeatureDefinition {
+  return {
+    name: "text-content",
+    treeProvider,
+    treeActions: {
+      edit: { args: { slug: "" as string, lang: "" as string } },
+      list: {},
+      create: { args: { folder: "" as string } },
+    },
+  };
+}

package/src/text-content/web/index.ts

@@ -0,0 +1,8 @@
+// @runtime client
+// Public exports für die Browser-Seite des text-content Features.
+// Wird über den Sub-Path-Export `@cosmicdrift/kumiko-bundled-features/text-content/web`
+// konsumiert — die Server-Seite (defineFeature) lebt in
+// `@cosmicdrift/kumiko-bundled-features/text-content` und hat keine
+// React-/DOM-Deps. Trennung bleibt sauber so wie renderer vs renderer-web.
+
+export { textContentClient } from "./client-plugin";

package/src/tier-engine/feature.ts

@@ -197,7 +197,7 @@ export function createTierEngineFeature<
     // Invalidation: tier-assignment events update the cache.
     r.entityHook("postSave", "tier-assignment", async (result) => {
       // result.data has tenantId + tier (after entity-update merge)
-      const data = result.data as { tenantId?: unknown; tier?: unknown };
+      const data = result.data as { tenantId?: unknown; tier?: unknown }; // @cast-boundary engine-payload
       // skip: defensive type-guard auf payload-shape. Bei korrekt gerenderten
       // entity-events sind beide fields immer strings; ein malformed-payload
       // (custom-handler-bug) würde hier silent zum cache-skip führen statt
@@ -210,7 +210,7 @@ export function createTierEngineFeature<
       );
     });
     r.entityHook("postDelete", "tier-assignment", async (payload) => {
-      const data = payload.data as { tenantId?: unknown };
+      const data = payload.data as { tenantId?: unknown }; // @cast-boundary engine-payload
       // skip: gleiche type-guard semantik wie postSave-hook oben.
       if (typeof data.tenantId !== "string") return;
       cache.delete(data.tenantId as TenantId);
@@ -235,16 +235,16 @@ export function createTierEngineFeature<
         "tenant",
         async (result, ctx) => {
           // result-shape: kumiko-framework's SaveContext mit isNew + data
-          const saveResult = result as { isNew?: unknown; data?: unknown };
+          const saveResult = result as { isNew?: unknown; data?: unknown }; // @cast-boundary engine-payload
           // skip: nur bei tenant-create (initial) — tenant-updates feuern
           // auch postSave aber wir wollen kein neues tier-assignment bei
           // re-keying oder name-update.
           if (saveResult.isNew !== true) return;
-          const data = saveResult.data as { id?: unknown };
+          const data = saveResult.data as { id?: unknown }; // @cast-boundary engine-payload
           // skip: defensive type-guard. Tenant-entity hat id zwingend, aber
           // CrudExecutor's payload-shape ist runtime-unknown.
           if (typeof data.id !== "string") return;
-          const newTenantId = data.id as TenantId;
+          const newTenantId = data.id as TenantId; // @cast-boundary engine-payload
           const aggregateId = tierAssignmentAggregateId(newTenantId);
 
           // skip: defensive — inTransaction phase hat ctx.db immer gesetzt,
@@ -268,7 +268,7 @@ export function createTierEngineFeature<
           // `as TenantDb` gegen future refactor.
           // skip: defensive — sollte im inTransaction nie greifen.
           if (!("raw" in ctx.db)) return;
-          const rawDb = ctx.db.raw as DbConnection;
+          const rawDb = ctx.db.raw as DbConnection; // @cast-boundary db-runner
 
           // Idempotency: stream-existence-check vor create. Pattern aus
           // seedTenant.ts. Bei re-replay (rebuild) nicht versionsbumpen.
@@ -276,7 +276,7 @@ export function createTierEngineFeature<
           const [streamRow] = (await rawDb
             .select({ v: maxFn(eventsTable.version) })
             .from(eventsTable)
-            .where(eq(eventsTable.aggregateId, aggregateId))) as StreamRow[];
+            .where(eq(eventsTable.aggregateId, aggregateId))) as StreamRow[]; // @cast-boundary db-row
           // skip: idempotency — aggregate-stream existiert schon (re-replay
           // nach projection-rebuild oder hook-retry). create() würde
           // version_conflict werfen + tenant-create rollback'n. Pattern aus
@@ -336,7 +336,7 @@ export function createTierEngineFeature<
         // Skalierungs-Pfad (lazy-load + LRU) ist Sprint-8b wenn echtes
         // Bedürfnis entsteht.
         type AssignmentRow = { tenantId: string; tier: string };
-        const rows = (await deps.db.select().from(tierAssignmentTable)) as AssignmentRow[];
+        const rows = (await deps.db.select().from(tierAssignmentTable)) as AssignmentRow[]; // @cast-boundary db-row
         for (const row of rows) {
           cache.set(
             row.tenantId as TenantId,

package/src/user/handlers/find-for-auth.query.ts

@@ -30,7 +30,7 @@ export const findForAuthQuery = defineQueryHandler({
     const condition =
       query.payload.email !== undefined
         ? eq(userTable["email"], query.payload.email)
-        : eq(userTable["id"], query.payload.id as string);
+        : eq(userTable["id"], query.payload.id as string); // @cast-boundary engine-payload
 
     const [row] = await ctx.db.select().from(userTable).where(condition).limit(1);
     return (row as DbRow) ?? null;

package/src/user/seeding.ts

@@ -57,7 +57,7 @@ export async function seedUser(db: DbConnection, options: SeedUserOptions): Prom
   const tdb = createTenantDb(db, by.tenantId, "system");
 
   const existing = await fetchOne(db, userTable, eq(userTable["email"], options.email));
-  if (existing) return existing["id"] as string;
+  if (existing) return existing["id"] as string; // @cast-boundary db-row
 
   const result = await userExecutor.create(
     {
@@ -86,7 +86,7 @@ export async function seedUser(db: DbConnection, options: SeedUserOptions): Prom
 // als ehrlicher Throw rauskommt statt downstream als undefined-Bug.
 function extractId(data: unknown, who: string): string {
   if (typeof data === "object" && data !== null && "id" in data) {
-    const id = (data as { id: unknown }).id;
+    const id = (data as { id: unknown }).id; // @cast-boundary engine-bridge
     if (typeof id === "string") return id;
   }
   throw new Error(`${who}: executor.create result has no string id (got ${JSON.stringify(data)})`);

package/src/user-data-rights/feature.ts

@@ -238,7 +238,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           _userId: ctx._userId ?? SYSTEM_USER_ID,
         };
         await runExportJobs({
-          db: ctx.db as import("@cosmicdrift/kumiko-framework/db").DbConnection,
+          db: ctx.db as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator
           registry: ctx.registry,
           buildStorageProvider: async (tenantId) =>
             createFileProviderForTenant(providerCtx, tenantId, "user-data-rights:run-export-jobs"),
@@ -268,11 +268,12 @@ async function mapQueryResponseToRedirect(
 ): Promise<Response> {
   if (!queryRes.ok) {
     const errorBody = await queryRes.text();
-    return c.body(errorBody, queryRes.status as 400 | 401 | 404 | 410 | 500, {
+    const statusCode = queryRes.status as 400 | 401 | 404 | 410 | 500; // @cast-boundary engine-payload
+    return c.body(errorBody, statusCode, {
       "content-type": queryRes.headers.get("content-type") ?? "application/json",
     });
   }
-  const body = (await queryRes.json()) as { data?: { url?: string } };
+  const body = (await queryRes.json()) as { data?: { url?: string } }; // @cast-boundary engine-payload
   if (!body.data?.url) {
     return c.json({ error: "download_resolution_failed" }, 500);
   }

package/src/user-data-rights/handlers/cancel-deletion.write.ts

@@ -77,7 +77,7 @@ export const cancelDeletionWrite = defineWriteHandler({
       data: {
         userId: event.user.id,
         status: USER_STATUS.Active,
-        gracePeriodEnd: null as string | null,
+        gracePeriodEnd: null as string | null, // @cast-boundary generic-record
       },
     };
   },

package/src/user-data-rights/handlers/download-by-job.query.ts

@@ -80,11 +80,11 @@ export const downloadByJobQuery = defineQueryHandler({
       ctx.db.raw,
       exportJobsTable,
       eq(exportJobsTable["id"], jobId),
-    )) as JobRow | null;
+    )) as JobRow | null; // @cast-boundary db-row
 
     if (!jobRow || jobRow.userId !== userId) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as DbConnection,
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
         tenantId,
         now,
         result: "notFound",
@@ -102,7 +102,7 @@ export const downloadByJobQuery = defineQueryHandler({
 
     if (jobRow.status !== EXPORT_JOB_STATUS.Done) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as DbConnection,
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
         tenantId,
         now,
         result: "failed",
@@ -119,7 +119,7 @@ export const downloadByJobQuery = defineQueryHandler({
     }
     if (!jobRow.downloadStorageKey) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as DbConnection,
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
         tenantId,
         now,
         result: "expired",
@@ -142,7 +142,7 @@ export const downloadByJobQuery = defineQueryHandler({
     );
     if (!provider.getSignedUrl) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as DbConnection,
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
         tenantId,
         now,
         result: "signedUrlNotSupported",
@@ -177,20 +177,17 @@ export const downloadByJobQuery = defineQueryHandler({
       ctx.db.raw,
       exportDownloadTokensTable,
       eq(exportDownloadTokensTable["jobId"], jobId),
-    )) as TokenRow | null;
+    )) as TokenRow | null; // @cast-boundary db-row
 
     if (tokenRow) {
       await recordDownloadUse({
-        // @cast-boundary db: ctx.db.raw ist DbRunner, im query-pfad immer
-        // Connection. Cast legit weil recordDownloadUse intern createTenantDb
-        // braucht.
-        db: ctx.db.raw as DbConnection,
+        db: ctx.db.raw as DbConnection, // @cast-boundary db-runner
         tokenId: tokenRow.id,
         tokenVersion: tokenRow.version,
         tokenUseCount: tokenRow.useCount ?? 0,
         tenantId: jobRow.requestedFromTenantId as Parameters<
           typeof recordDownloadUse
-        >[0]["tenantId"],
+        >[0]["tenantId"], // @cast-boundary engine-bridge
         now,
         ip: query.payload.auditMeta?.ip ?? null,
         userAgent: query.payload.auditMeta?.userAgent ?? null,