@cosmicdrift/kumiko-bundled-features 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @cosmicdrift/kumiko-bundled-features
 
+## 0.3.0
+
+### Minor Changes
+
+- 0.3.0 bringt zwei neue Subsysteme (Step-Engine Tier-3 + Visual-Tree) plus
+  eine AST-Codemod-Pipeline als Vorarbeit für den L2-AI-Layer.
+
+  ### Breaking Changes
+
+  - `skipTransitionGuard` → `unsafeSkipTransitionGuard` (Rename in
+    feature-ast + engine). Der `unsafe`-Prefix macht die Tragweite des
+    Casts sichtbar und ist konsistent zur `unsafeProjectionUpsert`- und
+    `r.rawTable`-Konvention. Migration: 1:1-Ersetzung, keine Verhaltens-Änderung.
+
+  ### Features
+
+  - **Step-Engine M.4 — Tier-3 Workflow-Engine.** Neue Step-Vocabulary
+    `wait`, `waitForEvent`, `retry` ermöglicht persistierte Long-Running-Flows
+    über Job-Boundaries hinweg. Q7 Snapshot-at-Start hängt jedem Step-Run
+    einen SHA-256-Fingerprint des Aggregat-Zustands an, sodass Replays
+    deterministisch gegen den ursprünglichen Eingangszustand laufen.
+  - **Visual-Tree V.1.x — Tree-API + Editor-Panel.** Neue `VisualTree`-
+    Component plus TreeProvider-Pattern; erste TreeProviders für
+    `text-content` und `legal-pages` (CMS-light + Impressum/Privacy).
+    Fundament für den späteren No-Code-Designer (~3000 LOC, 98 Tests).
+  - **Codemod-Pipeline.** AST-basierte Patcher-Module für strukturelle
+    Feature-Edits — wird vom kommenden L2-AI-Layer als Tool-Surface
+    verwendet, ist aber eigenständig nutzbar für ts-morph-style Migrationen.
+  - **user-data-rights Sample-Recipe.** DSGVO Art. 15/17/18/20 vollständig
+    als Sample-Recipe (`samples/recipes/`) inklusive README — zeigt die
+    Export- und Forget-Pipeline gegen den `compliance-profiles`-Default
+    (`eu-dsgvo`).
+
+  ### Fixes
+
+  - `tier-engine`: auto-default-tier-Hook benutzt jetzt `ctx.db.raw` für
+    Event-Store-Operationen (#37, vorher: stiller Bug, 22 Tage live).
+  - `engine`: unsafe-projection-upsert nutzt `as never` statt `as any` —
+    schmaler Cast-Surface, weniger Compiler-Knebel.
+  - `visual-tree`: runtime-isolation marker für client-konsumierte Files,
+    damit der Multi-Entry-Build den richtigen Bundle-Split bekommt.
+  - `feature-ast`: vollständiger `unsafeSkipTransitionGuard`-Rename (war
+    in zwei Modulen noch der alte Name).
+  - `framework`: Error-Reasons + `noConsole`-Lint + No-Date-API-Guard
+    wieder push-ready.
+
+  ### Library-Updates
+
+  hono 4.12, jose 6.2, stripe 22.1, meilisearch 0.58, marked 18,
+  bun-types 1.3.13, lucide-react 1.14, bullmq 5.76, ioredis 5.10,
+  i18next 26.0, react + radix-ui-primitives auf aktuelle Minors.
+
+### Patch Changes
+
+- Updated dependencies
+  - @cosmicdrift/kumiko-framework@0.3.0
+  - @cosmicdrift/kumiko-dispatcher-live@0.3.0
+  - @cosmicdrift/kumiko-renderer@0.3.0
+  - @cosmicdrift/kumiko-renderer-web@0.3.0
+
 ## 0.2.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -63,26 +63,29 @@
     "./feature-toggles": "./src/feature-toggles/index.ts",
     "./text-content": "./src/text-content/index.ts",
     "./text-content/seeding": "./src/text-content/seeding.ts",
-    "./legal-pages": "./src/legal-pages/index.ts"
+    "./text-content/web": "./src/text-content/web/index.ts",
+    "./legal-pages": "./src/legal-pages/index.ts",
+    "./legal-pages/web": "./src/legal-pages/web/index.ts",
+    "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.700.0",
-    "@aws-sdk/lib-storage": "^3.700.0",
-    "@aws-sdk/s3-request-presigner": "^3.700.0",
-    "@cosmicdrift/kumiko-dispatcher-live": "0.2.3",
-    "@cosmicdrift/kumiko-framework": "0.2.3",
-    "@cosmicdrift/kumiko-renderer": "0.2.3",
-    "@cosmicdrift/kumiko-renderer-web": "0.2.3",
+    "@aws-sdk/client-s3": "^3.1045.0",
+    "@aws-sdk/lib-storage": "^3.1045.0",
+    "@aws-sdk/s3-request-presigner": "^3.1045.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.3.0",
+    "@cosmicdrift/kumiko-framework": "0.3.0",
+    "@cosmicdrift/kumiko-renderer": "0.3.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.3.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.11.0",
-    "marked": "^14.1.3",
+    "lucide-react": "^1.14.0",
+    "marked": "^18.0.3",
     "nodemailer": "^8.0.7",
-    "react": "^19.2.0",
-    "stripe": "^22.1.0",
-    "tailwind-merge": "^3.0.2"
+    "react": "^19.2.6",
+    "stripe": "^22.1.1",
+    "tailwind-merge": "^3.6.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/auth-email-password/handlers/change-password.write.ts

@@ -30,7 +30,7 @@ export const changePasswordWrite = defineWriteHandler({
     // Load self with passwordHash — only visible to the privileged caller.
     const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
       id: event.user.id,
-    })) as { id: number; passwordHash: string | null; version: number } | null;
+    })) as { id: number; passwordHash: string | null; version: number } | null; // @cast-boundary db-runner
 
     if (!me?.passwordHash) {
       return invalidCredentials();

package/src/auth-email-password/handlers/confirm-token-flow.ts

@@ -152,7 +152,7 @@ async function resolveStreamTenants(
 ): Promise<readonly TenantId[]> {
   const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
     userId: me.id,
-  })) as Array<{ tenantId: TenantId }>;
+  })) as Array<{ tenantId: TenantId }>; // @cast-boundary db-runner
   return orderTenantsByPreference(memberships, me.lastActiveTenantId);
 }
 

package/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -114,10 +114,10 @@ export function createInviteAcceptWithLoginHandler() {
         if (!invitation || invitation["status"] !== INVITATION_STATUS.pending)
           return invalidInviteToken();
 
-        const invitationTenantId = invitation["tenantId"] as TenantId;
-        const invitationEmail = invitation["email"] as string;
-        const invitationRole = invitation["role"] as string;
-        const invitationVersion = invitation["version"] as number;
+        const invitationTenantId = invitation["tenantId"] as TenantId; // @cast-boundary db-row
+        const invitationEmail = invitation["email"] as string; // @cast-boundary db-row
+        const invitationRole = invitation["role"] as string; // @cast-boundary db-row
+        const invitationVersion = invitation["version"] as number; // @cast-boundary db-row
 
         // Email-Match vom User-Input (nicht aus session — User ist anon)
         if (event.payload.email.toLowerCase() !== invitationEmail) {
@@ -134,19 +134,19 @@ export function createInviteAcceptWithLoginHandler() {
         const userRow = await fetchOne(ctx.db.raw, userTable, eq(userTable.email, invitationEmail));
         if (!userRow?.["passwordHash"]) return invalidInviteToken();
         const passwordValid = await verifyPassword(
-          userRow["passwordHash"] as string,
+          userRow["passwordHash"] as string, // @cast-boundary db-row
           event.payload.password,
         );
         if (!passwordValid) return invalidInviteToken();
 
-        const userId = userRow["id"] as string;
+        const userId = userRow["id"] as string; // @cast-boundary db-row
 
         // Already-Member-Check (idempotent)
         const memberships = (await ctx.queryAs(
           createSystemUser(invitationTenantId),
           "tenant:query:memberships",
           { userId },
-        )) as Array<{ tenantId: string }>;
+        )) as Array<{ tenantId: string }>; // @cast-boundary db-row
         const alreadyMember = memberships.some((m) => m.tenantId === invitationTenantId);
 
         // @cast-boundary db-runner — TenantDb.raw is DbRunner

package/src/auth-email-password/handlers/invite-accept.write.ts

@@ -107,16 +107,17 @@ export function createInviteAcceptHandler() {
         if (!invitation || invitation["status"] !== INVITATION_STATUS.pending)
           return invalidInviteToken();
 
-        const invitationTenantId = invitation["tenantId"] as TenantId;
-        const invitationEmail = invitation["email"] as string;
-        const invitationRole = invitation["role"] as string;
-        const invitationVersion = invitation["version"] as number;
+        const invitationTenantId = invitation["tenantId"] as TenantId; // @cast-boundary db-row
+        const invitationEmail = invitation["email"] as string; // @cast-boundary db-row
+        const invitationRole = invitation["role"] as string; // @cast-boundary db-row
+        const invitationVersion = invitation["version"] as number; // @cast-boundary db-row
 
         // Email-Match: User muss mit der eingeladenen Email matchen.
         // Sonst kann ein Angreifer mit Zugriff zur invitee-Mail seinen
         // eigenen Account dem Tenant zuschlagen.
         const userRow = await fetchOne(ctx.db.raw, userTable, eq(userTable.id, event.user.id));
-        if (!userRow || (userRow["email"] as string).toLowerCase() !== invitationEmail) {
+        const userEmail = userRow?.["email"] as string | undefined; // @cast-boundary db-row
+        if (!userRow || !userEmail || userEmail.toLowerCase() !== invitationEmail) {
           return writeFailure(
             new UnprocessableError(AuthErrors.inviteEmailMismatch, {
               i18nKey: "auth.errors.inviteEmailMismatch",
@@ -131,7 +132,7 @@ export function createInviteAcceptHandler() {
           createSystemUser(invitationTenantId),
           "tenant:query:memberships",
           { userId: event.user.id },
-        )) as Array<{ tenantId: string }>;
+        )) as Array<{ tenantId: string }>; // @cast-boundary db-row
         const alreadyMember = memberships.some((m) => m.tenantId === invitationTenantId);
 
         // @cast-boundary db-runner — TenantDb.raw is DbRunner

package/src/auth-email-password/handlers/invite-create.write.ts

@@ -87,8 +87,8 @@ export function createInviteCreateHandler(opts: InviteCreateOptions = {}) {
       let invitationId: string;
       let token: string;
       if (existing) {
-        invitationId = existing["id"] as string;
-        const existingVersion = existing["version"] as number;
+        invitationId = existing["id"] as string; // @cast-boundary db-row
+        const existingVersion = existing["version"] as number; // @cast-boundary db-row
         // Resend-Idempotenz: Token aus Redis re-use wenn noch lebend.
         // Sonst neuen mintinen (alter ist abgelaufen).
         const existingToken = await getTokenForInvitation(ctx.redis, invitationId);
@@ -122,7 +122,7 @@ export function createInviteCreateHandler(opts: InviteCreateOptions = {}) {
           ctx.db,
         );
         if (!createResult.isSuccess) return createResult;
-        invitationId = (createResult.data as { id: string }).id;
+        invitationId = (createResult.data as { id: string }).id; // @cast-boundary engine-payload
         token = generateToken();
       }
 

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -114,10 +114,10 @@ export function createInviteSignupCompleteHandler() {
         if (!invitation || invitation["status"] !== INVITATION_STATUS.pending)
           return invalidInviteToken();
 
-        const invitationTenantId = invitation["tenantId"] as TenantId;
-        const invitationEmail = invitation["email"] as string;
-        const invitationRole = invitation["role"] as string;
-        const invitationVersion = invitation["version"] as number;
+        const invitationTenantId = invitation["tenantId"] as TenantId; // @cast-boundary db-row
+        const invitationEmail = invitation["email"] as string; // @cast-boundary db-row
+        const invitationRole = invitation["role"] as string; // @cast-boundary db-row
+        const invitationVersion = invitation["version"] as number; // @cast-boundary db-row
 
         // User-Not-Exists-Check: wenn die Email schon registriert ist,
         // muss der User Branch 2 (acceptWithLogin) nutzen. Hier ist

package/src/auth-email-password/handlers/login.write.ts

@@ -180,7 +180,7 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       // invitation, so we refuse with a dedicated error.
       const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
         userId: found.id,
-      })) as Array<{ tenantId: TenantId; roles: readonly string[] }>;
+      })) as Array<{ tenantId: TenantId; roles: readonly string[] }>; // @cast-boundary db-runner
 
       if (memberships.length === 0) {
         return noMembership();

package/src/auth-email-password/handlers/logout.write.ts

@@ -1,4 +1,4 @@
-import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, pipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 // Logout — JWT is stateless, so server-side we only return OK. A future
@@ -8,5 +8,5 @@ export const logoutWrite = defineWriteHandler({
   name: "logout",
   schema: z.object({}),
   access: { roles: access.authenticated },
-  handler: async () => ({ isSuccess: true, data: { kind: "logged-out" } }),
+  perform: pipeline(({ r }) => [r.step.return({ isSuccess: true, data: { kind: "logged-out" } })]),
 });

package/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -117,7 +117,7 @@ export function createSignupConfirmHandler() {
           },
         });
 
-        const tenantId = generateId() as TenantId;
+        const tenantId = generateId() as TenantId; // @cast-boundary engine-payload
         // Display-Name aus email-prefix als sinnvolles Default; User kann
         // den Tenant-Namen + sein eigenes displayName später ändern.
         const displayName = email.split("@")[0] ?? email;

package/src/auth-email-password/web/auth-client.ts

@@ -244,7 +244,7 @@ export async function confirmSignup(
     body: JSON.stringify({ token, password }),
   });
   if (res.ok) {
-    const body = (await res.json()) as SignupConfirmSuccess;
+    const body = (await res.json()) as SignupConfirmSuccess; // @cast-boundary engine-payload
     return { ok: true, data: body };
   }
   return { ok: false, error: await parseTokenFailure(res) };

package/src/billing-foundation/events.ts

@@ -18,7 +18,7 @@ import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./constants";
 export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription" as const;
 
 // Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
-// FQN (für ctx.appendEventUnsafe + projection-apply-keys).
+// FQN (für ctx.unsafeAppendEvent + projection-apply-keys).
 export const SUBSCRIPTION_CREATED_EVENT_SHORT = "subscription-created" as const;
 export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated" as const;
 export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled" as const;

package/src/billing-foundation/feature.ts

@@ -41,7 +41,7 @@
 // (z.B. für analytics: "wie viele Wechsel im Monat?"), kommt ein
 // `subscription-provider-changed`-event-type später.
 
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { BILLING_FOUNDATION_FEATURE, SUBSCRIPTION_PROVIDER_EXTENSION } from "./constants";
 import {
   INVOICE_PAID_EVENT_QN,
@@ -70,53 +70,50 @@ import {
   subscriptionsProjectionTable,
 } from "./projection";
 
-export const billingFoundationFeature: FeatureDefinition = defineFeature(
-  BILLING_FOUNDATION_FEATURE,
-  (r) => {
-    // 5 fine-grained domain-events. Alle 5 nutzen denselben payload-
-    // shape (= subscription-state-snapshot); der event-type taggt was
-    // passiert ist. Future-consumer (billing-history, accounting)
-    // listenen direkt auf den event-type ohne payload-discriminator.
-    r.defineEvent(SUBSCRIPTION_CREATED_EVENT_SHORT, subscriptionEventPayloadSchema);
-    r.defineEvent(SUBSCRIPTION_UPDATED_EVENT_SHORT, subscriptionEventPayloadSchema);
-    r.defineEvent(SUBSCRIPTION_CANCELED_EVENT_SHORT, subscriptionEventPayloadSchema);
-    r.defineEvent(INVOICE_PAID_EVENT_SHORT, subscriptionEventPayloadSchema);
-    r.defineEvent(INVOICE_PAYMENT_FAILED_EVENT_SHORT, subscriptionEventPayloadSchema);
+export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
+  // 5 fine-grained domain-events. Alle 5 nutzen denselben payload-
+  // shape (= subscription-state-snapshot); der event-type taggt was
+  // passiert ist. Future-consumer (billing-history, accounting)
+  // listenen direkt auf den event-type ohne payload-discriminator.
+  r.defineEvent(SUBSCRIPTION_CREATED_EVENT_SHORT, subscriptionEventPayloadSchema);
+  r.defineEvent(SUBSCRIPTION_UPDATED_EVENT_SHORT, subscriptionEventPayloadSchema);
+  r.defineEvent(SUBSCRIPTION_CANCELED_EVENT_SHORT, subscriptionEventPayloadSchema);
+  r.defineEvent(INVOICE_PAID_EVENT_SHORT, subscriptionEventPayloadSchema);
+  r.defineEvent(INVOICE_PAYMENT_FAILED_EVENT_SHORT, subscriptionEventPayloadSchema);
 
-    // Inline projection: materialized current state in `read_subscriptions`.
-    // Apply läuft in derselben TX wie ctx.appendEventUnsafe — read-your-
-    // own-write ohne dispatcher-tick.
-    r.projection({
-      name: "subscription",
-      source: SUBSCRIPTION_AGGREGATE_TYPE,
-      table: subscriptionsProjectionTable,
-      apply: {
-        [SUBSCRIPTION_CREATED_EVENT_QN]: applySubscriptionCreated,
-        [SUBSCRIPTION_UPDATED_EVENT_QN]: applySubscriptionUpdated,
-        [SUBSCRIPTION_CANCELED_EVENT_QN]: applySubscriptionCanceled,
-        [INVOICE_PAID_EVENT_QN]: applyInvoicePaid,
-        [INVOICE_PAYMENT_FAILED_EVENT_QN]: applyInvoicePaymentFailed,
-      },
-    });
+  // Inline projection: materialized current state in `read_subscriptions`.
+  // Apply läuft in derselben TX wie ctx.unsafeAppendEvent — read-your-
+  // own-write ohne dispatcher-tick.
+  r.projection({
+    name: "subscription",
+    source: SUBSCRIPTION_AGGREGATE_TYPE,
+    table: subscriptionsProjectionTable,
+    apply: {
+      [SUBSCRIPTION_CREATED_EVENT_QN]: applySubscriptionCreated,
+      [SUBSCRIPTION_UPDATED_EVENT_QN]: applySubscriptionUpdated,
+      [SUBSCRIPTION_CANCELED_EVENT_QN]: applySubscriptionCanceled,
+      [INVOICE_PAID_EVENT_QN]: applyInvoicePaid,
+      [INVOICE_PAYMENT_FAILED_EVENT_QN]: applyInvoicePaymentFailed,
+    },
+  });
 
-    // Plugin extension-point. Provider-Plugins registrieren sich hier.
-    r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
-      onRegister: () => {
-        // No side-effects at register-time.
-      },
-    });
+  // Plugin extension-point. Provider-Plugins registrieren sich hier.
+  r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
+    onRegister: () => {
+      // No side-effects at register-time.
+    },
+  });
 
-    // Custom write-handlers:
-    //   - process-event: programmatic entry-point vom webhook-handler;
-    //     dispatcht zu type-passendem appendEvent
-    //   - create-checkout-session: Tenant-Admin "Upgrade to Pro"-flow
-    //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
-    r.writeHandler(processEventHandler);
-    r.writeHandler(createCheckoutSessionHandler);
-    r.writeHandler(createPortalSessionHandler);
+  // Custom write-handlers:
+  //   - process-event: programmatic entry-point vom webhook-handler;
+  //     dispatcht zu type-passendem appendEvent
+  //   - create-checkout-session: Tenant-Admin "Upgrade to Pro"-flow
+  //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
+  r.writeHandler(processEventHandler);
+  r.writeHandler(createCheckoutSessionHandler);
+  r.writeHandler(createPortalSessionHandler);
 
-    // Custom list-query auf der subscription-projection (raw drizzle-
-    // table; kein r.entity weil Schreiben via projection-apply läuft).
-    r.queryHandler(listSubscriptionsQuery);
-  },
-);
+  // Custom list-query auf der subscription-projection (raw drizzle-
+  // table; kein r.entity weil Schreiben via projection-apply läuft).
+  r.queryHandler(listSubscriptionsQuery);
+});

package/src/billing-foundation/handlers/create-portal-session.write.ts

@@ -28,7 +28,7 @@ export const createPortalSessionHandler: WriteHandlerDef = {
   schema: createPortalSessionSchema,
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   handler: async (event, ctx) => {
-    const payload = event.payload as CreatePortalSessionPayload;
+    const payload = event.payload as CreatePortalSessionPayload; // @cast-boundary engine-payload
     const tenantId = event.user.tenantId;
 
     // 1. Hol current subscription-row für den Tenant. Aggregate-id ist
@@ -41,8 +41,8 @@ export const createPortalSessionHandler: WriteHandlerDef = {
         "subscription-foundation: no active subscription for this tenant. Create one via create-checkout-session first.",
       );
     }
-    const providerName = row["providerName"] as string;
-    const providerCustomerId = row["providerCustomerId"] as string;
+    const providerName = row["providerName"] as string; // @cast-boundary db-row
+    const providerCustomerId = row["providerCustomerId"] as string; // @cast-boundary db-row
 
     // 2. Plugin-Lookup
     const usages = ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION);

package/src/billing-foundation/handlers/process-event.write.ts

@@ -9,7 +9,7 @@
 //      kein zweiter append.
 //   2. Type-mapping: SubscriptionEvent.type (= normalisiert vom Plugin)
 //      → einer der 5 ES-event-typen.
-//   3. ctx.appendEventUnsafe — Inline-projection materialisiert die
+//   3. ctx.unsafeAppendEvent — Inline-projection materialisiert die
 //      `read_subscriptions`-row in derselben TX.
 
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
@@ -69,7 +69,7 @@ const NORMALIZED_TO_ES_EVENT: Readonly<Record<string, string>> = {
   [SubscriptionEventTypes.canceled]: SUBSCRIPTION_CANCELED_EVENT_QN,
   [SubscriptionEventTypes.invoicePaid]: INVOICE_PAID_EVENT_QN,
   [SubscriptionEventTypes.invoicePaymentFailed]: INVOICE_PAYMENT_FAILED_EVENT_QN,
-};
+} satisfies Readonly<Record<string, string>>;
 
 // =============================================================================
 // Handler
@@ -141,7 +141,7 @@ export const processEventHandler: WriteHandlerDef = {
       providerName: payload.providerName,
       rawPayload: payload.rawPayload,
     };
-    await ctx.appendEventUnsafe({
+    await ctx.unsafeAppendEvent({
       aggregateId: aggId,
       aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
       type: esEventType,

package/src/billing-foundation/projection.ts

@@ -1,7 +1,7 @@
 // Inline-projection für `read_subscriptions`. Materialisiert die 5
 // subscription-events in eine row pro Tenant.
 //
-// Apply läuft in derselben TX wie ctx.appendEventUnsafe — Caller sieht
+// Apply läuft in derselben TX wie ctx.unsafeAppendEvent — Caller sieht
 // seinen Schreib-State sofort (kein dispatcher-tick nötig). PK = event.
 // aggregateId (= deterministic uuidv5 pro Tenant) → replays kollidieren
 // auf der PK statt doppelte rows zu erzeugen.

package/src/billing-foundation/webhook-handler.ts

@@ -169,7 +169,7 @@ export function createSubscriptionWebhookHandler(deps: SubscriptionWebhookDeps)
       );
     }
 
-    return c.json({ processed: true, ...((dispatched.data as object) ?? {}) }, 200);
+    return c.json({ processed: true, ...((dispatched.data as object) ?? {}) }, 200); // @cast-boundary engine-bridge
   };
 }
 

package/src/cap-counter/constants.ts

@@ -12,7 +12,7 @@ export const CAP_COUNTER_ROLLING_AGGREGATE_TYPE = "cap-counter-rolling" as const
 // Custom event-type für Rolling-Window-Counter. Symmetrisches Paar:
 //   _SHORT  — passt zu `r.defineEvent(short, schema)` im Registrar
 //             (Framework prefixt automatisch zu QN)
-//   _QN     — qualifizierte Form für `ctx.appendEventUnsafe({type})`
+//   _QN     — qualifizierte Form für `ctx.unsafeAppendEvent({type})`
 //             + `events.type`-Spalte + `registry.getEvent(qn)`-Lookup
 // Beide MÜSSEN konsistent sein (drift-pin im feature-test).
 export const ROLLING_INCREMENTED_EVENT_SHORT = "rolling-incremented" as const;

package/src/cap-counter/enforce-cap.ts

@@ -118,7 +118,7 @@ export async function enforceCap(
     .limit(1);
 
   const row = rows[0];
-  const value = row ? (row["value"] as number) : 0;
+  const value = row ? (row["value"] as number) : 0; // @cast-boundary db-row
 
   if (value >= hardThreshold) {
     throw new CapExceededError(options.capName, options.limit, value, tolerance);

package/src/cap-counter/feature.ts

@@ -46,11 +46,7 @@
 // config, kein secrets, kein tenant-feature nötig. Tenant-Scoping kommt
 // vom Framework-Default (Base-Column tenantId).
 
-import {
-  defineEntityListHandler,
-  defineFeature,
-  type FeatureDefinition,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineEntityListHandler, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { CAP_COUNTER_FEATURE, ROLLING_INCREMENTED_EVENT_SHORT } from "./constants";
 import { capCounterEntity } from "./entity";
 import { getCounterQuery } from "./handlers/get-counter.query";
@@ -63,11 +59,11 @@ import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write";
 
 const sysadminAccess = { access: { roles: ["SystemAdmin"] } } as const;
 
-export const capCounterFeature: FeatureDefinition = defineFeature(CAP_COUNTER_FEATURE, (r) => {
+export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
   r.entity("cap-counter", capCounterEntity);
 
   // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert
-  // das Schema beim Registry; ctx.appendEventUnsafe im Handler nutzt
+  // das Schema beim Registry; ctx.unsafeAppendEvent im Handler nutzt
   // dasselbe Schema für Append-Time-Validation. QN nach Prefixing:
   // "cap-counter:event:rolling-incremented" (siehe
   // ROLLING_INCREMENTED_EVENT_QN).

package/src/cap-counter/handlers/get-counter.query.ts

@@ -22,7 +22,7 @@ export const getCounterQuery: QueryHandlerDef = {
   schema: getCounterSchema,
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   handler: async (query, ctx) => {
-    const { capName, periodStartIso } = query.payload as z.infer<typeof getCounterSchema>;
+    const { capName, periodStartIso } = query.payload as z.infer<typeof getCounterSchema>; // @cast-boundary engine-payload
 
     // ctx.db is tenant-scoped; filter by capName + periodStart explicitly.
     const rows = await ctx.db

package/src/cap-counter/handlers/increment-rolling.write.ts

@@ -60,11 +60,11 @@ export const incrementRollingCapHandler: WriteHandlerDef = {
     const payload = event.payload as IncrementRollingPayload;
     const aggregateId = rollingCapAggregateId(event.user.tenantId, payload.capName);
 
-    // appendEventUnsafe — bundled-features-Pfad (apps mit yarn kumiko
+    // unsafeAppendEvent — bundled-features-Pfad (apps mit yarn kumiko
     // codegen kriegen den strict-typed appendEvent-Wrapper). Schema-
     // Validation läuft trotzdem, weil r.defineEvent das Schema
     // registriert hat.
-    await ctx.appendEventUnsafe({
+    await ctx.unsafeAppendEvent({
       aggregateId,
       aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
       type: ROLLING_INCREMENTED_EVENT_QN,

package/src/cap-counter/handlers/increment.write.ts

@@ -46,7 +46,7 @@ export const incrementCapHandler: WriteHandlerDef = {
   // which subsystem incremented.
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
-    const payload = event.payload as IncrementPayload;
+    const payload = event.payload as IncrementPayload; // @cast-boundary engine-payload
     const aggregateId = capCounterAggregateId(
       event.user.tenantId,
       payload.capName,
@@ -77,8 +77,8 @@ export const incrementCapHandler: WriteHandlerDef = {
       // clearer than a possibly-null deref later.
       throw new Error("cap-counter:increment: row vanished between length-check and read");
     }
-    const currentValue = currentRow["value"] as number;
-    const currentVersion = currentRow["version"] as number;
+    const currentValue = currentRow["value"] as number; // @cast-boundary db-row
+    const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
     return executor.update(
       {
         id: aggregateId,

package/src/cap-counter/handlers/mark-soft-warned.write.ts

@@ -25,7 +25,7 @@ export const markSoftWarnedHandler: WriteHandlerDef = {
   schema: markSoftWarnedSchema,
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
-    const payload = event.payload as z.infer<typeof markSoftWarnedSchema>;
+    const payload = event.payload as z.infer<typeof markSoftWarnedSchema>; // @cast-boundary engine-payload
     const aggregateId = capCounterAggregateId(
       event.user.tenantId,
       payload.capName,
@@ -42,7 +42,7 @@ export const markSoftWarnedHandler: WriteHandlerDef = {
     if (!row) {
       throw new Error("cap-counter:mark-soft-warned: row vanished between length-check and read");
     }
-    const currentVersion = row["version"] as number;
+    const currentVersion = row["version"] as number; // @cast-boundary db-row
 
     return executor.update(
       {

package/src/channel-email/email-channel.ts

@@ -34,7 +34,7 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
         template: message.notificationType,
         variables,
       });
-      const subject = (variables["subject"] as string) ?? message.title;
+      const subject = (variables["subject"] as string) ?? message.title; // @cast-boundary dynamic-key
 
       await transport.send({
         to: address,

package/src/channel-email/types.ts

@@ -20,7 +20,7 @@ export function createInMemoryTransport(): EmailTransport & {
   const sent: EmailMessage[] = [];
   const transport = {
     sent,
-    failNext: null as null | { message: string },
+    failNext: null as null | { message: string }, // @cast-boundary generic-record
     async send(message: EmailMessage) {
       if (transport.failNext) {
         const err = new Error(transport.failNext.message);