@cosmicdrift/kumiko-bundled-features 0.2.3 → 0.3.0

package/src/compliance-profiles/handlers/for-tenant.query.ts

@@ -26,7 +26,7 @@ export const forTenantQuery = defineQueryHandler({
       ctx.db,
       tenantComplianceProfileTable,
       eq(tenantComplianceProfileTable["tenantId"], query.user.tenantId),
-    )) as { profileKey: string; override: string | null } | null;
+    )) as { profileKey: string; override: string | null } | null; // @cast-boundary db-runner
 
     if (!row) {
       return resolveComplianceProfile({});
@@ -34,7 +34,7 @@ export const forTenantQuery = defineQueryHandler({
 
     const override = parseOverride(row.override, query.user.tenantId);
     return resolveComplianceProfile({
-      selection: row.profileKey as ComplianceProfileKey,
+      selection: row.profileKey as ComplianceProfileKey, // @cast-boundary engine-payload
       override,
     });
   },
@@ -46,9 +46,10 @@ function parseOverride(
 ): ComplianceProfileOverride | undefined {
   if (!raw || raw.trim() === "") return undefined;
   try {
-    const parsed = JSON.parse(raw) as ComplianceProfileOverride;
-    return parsed;
-  } catch (e) {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed as ComplianceProfileOverride; // @cast-boundary engine-payload
+  } catch (e: unknown) {
+    const reason = e instanceof Error ? e.message : String(e);
     // Defensiv: ungültiges JSON wird als "kein Override" behandelt. Der
     // set-profile-Handler validiert Zod das Override schon — invalides
     // JSON in der DB ist also nur möglich bei manueller DB-Manipulation
@@ -56,7 +57,7 @@ function parseOverride(
     // Operator-Sichtbarkeit via console.warn — Telemetry-Hook spaeter.
     // biome-ignore lint/suspicious/noConsole: operator visibility for DB-corruption edge-case
     console.warn(
-      `[compliance-profiles:for-tenant] tenant ${tenantId}: stored override is not valid JSON, falling back to base profile. Reason: ${(e as Error).message}`,
+      `[compliance-profiles:for-tenant] tenant ${tenantId}: stored override is not valid JSON, falling back to base profile. Reason: ${reason}`,
     );
     return undefined;
   }

package/src/compliance-profiles/handlers/needs-profile.query.ts

@@ -27,7 +27,7 @@ export const needsProfileQuery = defineQueryHandler({
       ctx.db,
       tenantComplianceProfileTable,
       eq(tenantComplianceProfileTable["tenantId"], query.user.tenantId),
-    )) as { profileKey: ComplianceProfileKey } | null;
+    )) as { profileKey: ComplianceProfileKey } | null; // @cast-boundary db-runner
 
     if (!row) {
       return {

package/src/compliance-profiles/handlers/set-profile.write.ts

@@ -1,6 +1,5 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import {
-  type ComplianceProfileKey,
   complianceProfileOverrideSchema,
   SELECTABLE_PROFILE_KEYS,
 } from "@cosmicdrift/kumiko-framework/compliance";
@@ -27,9 +26,7 @@ const crud = createEventStoreExecutor(tenantComplianceProfileTable, tenantCompli
 // X1) — minimal-no-region ist Default-Fallback fuer "noch keine Wahl",
 // nicht eine waehlbare Production-Option. Symmetrisch zu
 // SELECTABLE_PROFILE_KEYS aus der framework/compliance-Liste.
-const profileKeySchema = z.enum(
-  SELECTABLE_PROFILE_KEYS as readonly [ComplianceProfileKey, ...ComplianceProfileKey[]],
-);
+const profileKeySchema = z.enum(SELECTABLE_PROFILE_KEYS);
 
 // Tenant-Admin setzt Profile-Key + optional Override-JSON.
 //
@@ -69,7 +66,7 @@ export const setProfileWrite = defineWriteHandler({
         }),
       );
     }
-    const tenantId = (tenantOverride ?? event.user.tenantId) as TenantId;
+    const tenantId = (tenantOverride ?? event.user.tenantId) as TenantId; // @cast-boundary engine-payload
     const executorUser = tenantOverride !== undefined ? { ...event.user, tenantId } : event.user;
 
     // Override-Validation: muss parseables JSON-Object sein UND dem
@@ -85,12 +82,13 @@ export const setProfileWrite = defineWriteHandler({
       let parsed: unknown;
       try {
         parsed = JSON.parse(event.payload.override);
-      } catch (e) {
+      } catch (e: unknown) {
+        const parseError = e instanceof Error ? e.message : String(e);
         return writeFailure(
           new UnprocessableError("compliance_override_invalid_json", {
             details: {
               reason: "compliance_override_invalid_json",
-              parseError: (e as Error).message,
+              parseError,
             },
           }),
         );
@@ -106,7 +104,7 @@ export const setProfileWrite = defineWriteHandler({
       ctx.db,
       tenantComplianceProfileTable,
       eq(tenantComplianceProfileTable["tenantId"], tenantId),
-    )) as { id: string; version: number } | null;
+    )) as { id: string; version: number } | null; // @cast-boundary db-runner
 
     if (existing) {
       const result = await crud.update(

package/src/compliance-profiles/resolve-for-tenant.ts

@@ -31,7 +31,7 @@ export async function resolveProfileForTenant(
     args.db,
     tenantComplianceProfileTable,
     eq(tenantComplianceProfileTable["tenantId"], args.tenantId),
-  )) as { profileKey: string; override: string | null } | null;
+  )) as { profileKey: string; override: string | null } | null; // @cast-boundary db-runner
 
   if (!row) {
     return resolveComplianceProfile({});
@@ -39,7 +39,7 @@ export async function resolveProfileForTenant(
 
   const override = parseOverride(row.override, args.tenantId);
   return resolveComplianceProfile({
-    selection: row.profileKey as ComplianceProfileKey,
+    selection: row.profileKey as ComplianceProfileKey, // @cast-boundary engine-payload
     override,
   });
 }
@@ -50,11 +50,13 @@ function parseOverride(
 ): ComplianceProfileOverride | undefined {
   if (!raw || raw.trim() === "") return undefined;
   try {
-    return JSON.parse(raw) as ComplianceProfileOverride;
-  } catch (e) {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed as ComplianceProfileOverride; // @cast-boundary engine-payload
+  } catch (e: unknown) {
+    const reason = e instanceof Error ? e.message : String(e);
     // biome-ignore lint/suspicious/noConsole: operator visibility for DB-corruption edge-case
     console.warn(
-      `[compliance-profiles:resolve-for-tenant] tenant ${tenantId}: stored override is not valid JSON, ignoring. Reason: ${(e as Error).message}`,
+      `[compliance-profiles:resolve-for-tenant] tenant ${tenantId}: stored override is not valid JSON, ignoring. Reason: ${reason}`,
     );
     return undefined;
   }

package/src/compliance-profiles/seeding.ts

@@ -56,7 +56,7 @@ export async function seedComplianceProfile(
     db,
     tenantComplianceProfileTable,
     eq(tenantComplianceProfileTable["tenantId"], opts.tenantId),
-  )) as { id: string; version: number } | null;
+  )) as { id: string; version: number } | null; // @cast-boundary db-runner
 
   if (existing) {
     const result = await executor.update(

package/src/config/resolver.ts

@@ -179,7 +179,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
 
       const result = new Map<string, ConfigRow>();
       for (const row of rows) {
-        const r = row as ConfigRow;
+        const r = row as ConfigRow; // @cast-boundary db-row
         // Higher specificity wins: user > tenant > system. Under the ES
         // schema system rows carry SYSTEM_TENANT_ID instead of NULL, so the
         // "tenant set" check compares against the sentinel rather than null.

package/src/data-retention/_internal/parse-override.ts

@@ -14,10 +14,11 @@ export function parseRetentionOverrideOrNull(
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw);
-  } catch (e) {
+  } catch (e: unknown) {
+    const reason = e instanceof Error ? e.message : String(e);
     // biome-ignore lint/suspicious/noConsole: operator visibility for DB-corruption edge-case
     console.warn(
-      `[${callerLabel}] tenant ${tenantId}: stored override is not valid JSON, ignoring. Reason: ${(e as Error).message}`,
+      `[${callerLabel}] tenant ${tenantId}: stored override is not valid JSON, ignoring. Reason: ${reason}`,
     );
     return null;
   }

package/src/data-retention/handlers/policy-for.query.ts

@@ -33,7 +33,7 @@ export const policyForQuery = defineQueryHandler({
       tenantRetentionOverrideTable,
       eq(tenantRetentionOverrideTable["tenantId"], query.user.tenantId),
       eq(tenantRetentionOverrideTable["entityName"], entityName),
-    )) as { config: string | null } | null;
+    )) as { config: string | null } | null; // @cast-boundary db-runner
 
     const tenantOverride = parseRetentionOverrideOrNull(
       overrideRow?.config ?? null,

package/src/data-retention/keep-for.ts

@@ -19,7 +19,7 @@ const UNIT_TO_DAYS: Readonly<Record<string, number>> = {
   w: 7,
   m: 30,
   y: 365,
-};
+} satisfies Readonly<Record<string, number>>;
 
 export class InvalidKeepForError extends Error {
   constructor(spec: string) {

package/src/data-retention/presets.ts

@@ -58,7 +58,7 @@ export const RETENTION_PRESETS: Readonly<Record<RetentionPresetKey, RetentionPre
     session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
     invoice: { keepFor: "10y", strategy: "blockDelete", reference: "createdAt" },
   },
-};
+} satisfies Readonly<Record<RetentionPresetKey, RetentionPreset>>;
 
 /**
  * Auswählbare Presets für den Onboarding-Banner. "default" ist Migration-

package/src/data-retention/resolve-for-tenant.ts

@@ -28,7 +28,7 @@ export async function resolveRetentionPolicyForTenant(
     tenantRetentionOverrideTable,
     eq(tenantRetentionOverrideTable["tenantId"], args.tenantId),
     eq(tenantRetentionOverrideTable["entityName"], args.entityName),
-  )) as { config: string | null } | null;
+  )) as { config: string | null } | null; // @cast-boundary db-runner
 
   const tenantOverride = parseRetentionOverrideOrNull(
     overrideRow?.config ?? null,

package/src/delivery/feature.ts

@@ -31,7 +31,7 @@ export function createDeliveryFeature(): FeatureDefinition {
       table: deliveryAttemptsTable,
       apply: {
         [DELIVERY_ATTEMPT_EVENT]: async (event, tx) => {
-          const p = event.payload as z.infer<typeof deliveryAttemptSchema>;
+          const p = event.payload as z.infer<typeof deliveryAttemptSchema>; // @cast-boundary engine-payload
           // PK = aggregateId — replaying the same event twice conflicts on
           // the PK rather than silently duplicating the log row.
           await tx.insert(deliveryAttemptsTable).values({

package/src/delivery/testing.ts

@@ -41,7 +41,6 @@ export function createDeliveryTestContext(
     _notifyFactory:
       (user: { id: number; tenantId: TenantId }, tenantId: TenantId) =>
       (notificationType: string, notifyOptions: Record<string, unknown>) =>
-        // @cast-boundary engine-bridge — generic test-helper → typed entity-specific notify()
-        deliveryService.notify(notificationType, notifyOptions as never, user as never, tenantId),
+        deliveryService.notify(notificationType, notifyOptions as never, user as never, tenantId), // @cast-boundary engine-bridge
   };
 }

package/src/delivery/upsert-preference.ts

@@ -137,7 +137,7 @@ export async function upsertPreference(
 // minor driver-version shifts without drifting wide.
 function isUniqueViolation(err: unknown): boolean {
   if (typeof err !== "object" || err === null) return false;
-  const e = err as { code?: unknown; cause?: { code?: unknown }; message?: unknown };
+  const e = err as { code?: unknown; cause?: { code?: unknown }; message?: unknown }; // @cast-boundary error-details
   if (e.code === "23505") return true;
   if (e.cause && typeof e.cause === "object" && e.cause.code === "23505") return true;
   if (typeof e.message === "string" && e.message.includes("23505")) return true;

package/src/feature-toggles/feature.ts

@@ -78,7 +78,7 @@ export function createFeatureTogglesFeature(options: FeatureTogglesOptions): Fea
           // (validated on append). Shallow-cast to a typed shape rather
           // than re-parsing — the payload round-trips through JSON and is
           // fixed at the source.
-          const payload = event.payload as { featureName: string; enabled: boolean };
+          const payload = event.payload as { featureName: string; enabled: boolean }; // @cast-boundary engine-payload
           options.getRuntime().apply(payload.featureName, payload.enabled);
         },
       },

package/src/feature-toggles/handlers/list.query.ts

@@ -12,7 +12,7 @@ export const listQuery = defineQueryHandler({
   access: { roles: ["SystemAdmin", "Admin"] },
   handler: async (_event, ctx) => {
     type Row = typeof globalFeatureStateTable.$inferSelect;
-    const rows = (await ctx.db.select().from(globalFeatureStateTable)) as Row[];
+    const rows = (await ctx.db.select().from(globalFeatureStateTable)) as Row[]; // @cast-boundary db-row
     return {
       items: rows.map((r) => ({
         featureName: r.featureName,

package/src/feature-toggles/handlers/registered.query.ts

@@ -21,7 +21,7 @@ export const registeredQuery = defineQueryHandler({
         featureName: globalFeatureStateTable.featureName,
         enabled: globalFeatureStateTable.enabled,
       })
-      .from(globalFeatureStateTable)) as OverrideRow[];
+      .from(globalFeatureStateTable)) as OverrideRow[]; // @cast-boundary db-row
     const overrides = new Map(overrideRows.map((r) => [r.featureName, r.enabled]));
 
     // SystemAdmin operator-tooling: das listing soll die PLATTFORM-truth
@@ -31,7 +31,14 @@ export const registeredQuery = defineQueryHandler({
     // dokumentiert in DispatcherOptions.effectiveFeatures.
     const effective = ctx.effectiveFeatures?.(SYSTEM_TENANT_ID);
 
-    const items = [];
+    const items: Array<{
+      name: string;
+      toggleable: boolean;
+      default: boolean | null;
+      override: boolean | null;
+      requires: readonly string[];
+      effective: boolean | null;
+    }> = [];
     for (const feature of ctx.registry.features.values()) {
       const toggleable = feature.toggleableDefault !== undefined;
       const override = overrides.get(feature.name);

package/src/feature-toggles/handlers/set.write.ts

@@ -71,7 +71,7 @@ export function createSetWriteHandler(getRuntime: () => GlobalFeatureToggleRunti
         .select()
         .from(globalFeatureStateTable)
         .where(eq(globalFeatureStateTable.featureName, featureName))
-        .limit(1)) as StateRow[];
+        .limit(1)) as StateRow[]; // @cast-boundary db-row
 
       const previousEnabled = existing?.enabled ?? null;
 
@@ -123,11 +123,11 @@ export function createSetWriteHandler(getRuntime: () => GlobalFeatureToggleRunti
       // and filtering by payload.featureName is trivial at query time.
       // This mirrors how `config` handles the same constraint for
       // its config-changed events.
-      // appendEventUnsafe — bundled-features ohne lokalen Wrapper. Apps
+      // unsafeAppendEvent — bundled-features ohne lokalen Wrapper. Apps
       // mit `yarn kumiko codegen` kriegen `.kumiko/define.ts` als strict-
       // path; bundled-features bleibt bei der unsafe-Variante. Schema-
       // Validation läuft trotzdem via r.defineEvent("toggle-set", ...).
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: SYSTEM_TENANT_ID,
         aggregateType: FEATURE_TOGGLE_AGGREGATE_TYPE,
         type: FEATURE_TOGGLE_SET_EVENT_NAME,

package/src/file-foundation/feature.ts

@@ -137,7 +137,7 @@ export async function createFileProviderForTenant(
     await ctxConfig(fileFoundationFeature.exports.configKeys.provider),
     FEATURE_NAME,
     "provider",
-  ) as string;
+  ) as string; // @cast-boundary engine-payload
   if (provider.length === 0) {
     const usages = ctx.registry.getExtensionUsages("fileProvider");
     const known = usages.map((u) => u.entityName).join(", ") || "<none>";

package/src/file-provider-s3/feature.ts

@@ -129,13 +129,13 @@ async function buildS3Provider(
     await ctxConfig(fileProviderS3Feature.exports.configKeys.endpoint),
     FEATURE_NAME,
     "endpoint",
-  ) as string;
+  ) as string; // @cast-boundary engine-payload
   const endpoint = endpointRaw.length > 0 ? endpointRaw : undefined;
   const forcePathStyle = requireDefined(
     await ctxConfig(fileProviderS3Feature.exports.configKeys.forcePathStyle),
     FEATURE_NAME,
     "forcePathStyle",
-  ) as boolean;
+  ) as boolean; // @cast-boundary engine-payload
   const accessKeyId = requireNonEmpty(
     await ctxConfig(fileProviderS3Feature.exports.configKeys.accessKeyId),
     FEATURE_NAME,

package/src/files-provider-s3/s3-provider.ts

@@ -154,7 +154,7 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
           }
           // SdkStream is AsyncIterable<Buffer> on node. Buffer extends
           // Uint8Array; cast sichert die Surface ohne neue runtime-deps.
-          const body = response.Body as AsyncIterable<Uint8Array>;
+          const body = response.Body as AsyncIterable<Uint8Array>; // @cast-boundary engine-bridge
           for await (const chunk of body) {
             yield chunk;
           }
@@ -174,7 +174,7 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
         // S3 SDK throws either NotFound or a generic 404. Check both the
         // `.name` property (newer SDKs) and the `$metadata.httpStatusCode`
         // (what the SDK guarantees on every error).
-        const err = error as { name?: string; $metadata?: { httpStatusCode?: number } };
+        const err = error as { name?: string; $metadata?: { httpStatusCode?: number } }; // @cast-boundary error-details
         if (err.name === "NotFound" || err.$metadata?.httpStatusCode === 404) {
           return false;
         }

package/src/jobs/handlers/list.query.ts

@@ -1,5 +1,5 @@
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { and, desc, eq } from "drizzle-orm";
+import { and, desc, eq, type SQL } from "drizzle-orm";
 import { z } from "zod";
 import { type JobRunStatus, jobRunsTable } from "../job-run-table";
 
@@ -13,13 +13,13 @@ export const listQuery = defineQueryHandler({
   access: { roles: ["SystemAdmin"] },
   handler: async (query, ctx) => {
     const db = ctx.db;
-    const conditions = [];
+    const conditions: SQL[] = [];
 
     if (query.payload.jobName) {
       conditions.push(eq(jobRunsTable.jobName, query.payload.jobName));
     }
     if (query.payload.status) {
-      conditions.push(eq(jobRunsTable.status, query.payload.status as JobRunStatus));
+      conditions.push(eq(jobRunsTable.status, query.payload.status as JobRunStatus)); // @cast-boundary engine-payload
     }
 
     const limit = query.payload.limit ?? 50;

package/src/jobs/handlers/trigger.write.ts

@@ -14,7 +14,7 @@ export const triggerWrite = defineWriteHandler({
   handler: async (event, ctx) => {
     const registry = ctx.registry;
     // `jobRunner` is a dynamic context extension — not a core HandlerContext field.
-    const jobRunner = ctx["jobRunner"] as JobRunner;
+    const jobRunner = ctx["jobRunner"] as JobRunner; // @cast-boundary dynamic-key
 
     const jobDef = registry.getJob(event.payload.jobName);
     if (!jobDef) {

package/src/legal-pages/constants.ts

@@ -1,3 +1,4 @@
+// @runtime client
 // Feature name
 export const LEGAL_PAGES_FEATURE = "legal-pages" as const;
 

package/src/legal-pages/web/client-plugin.ts

@@ -0,0 +1,42 @@
+// @runtime client
+// Client-Feature-Factory für legal-pages Visual-Tree. Liefert statische
+// Tree-Knoten für die DACH-Compliance-Blöcke (imprint, privacy in de/en).
+// Jeder Knoten linkt auf text-content's edit-Action — reines Cross-Feature-
+// Linking, kein eigener State oder Fetch nötig.
+//
+// **Static statt fetch**: legal-pages weiß out-of-the-box welche Blocks
+// existieren (LEGAL_REQUIRED_BLOCKS + LEGAL_OPTIONAL_BLOCKS aus constants).
+// Anders als text-content's Provider (der alle Slugs des Tenants holt)
+// ist diese Liste bekannt zur Build-Zeit — kein /api/query-Round-trip nötig.
+//
+// **Content-State unbekannt**: V.1.2 setzt keine state-Markierung; alle
+// Knoten erscheinen "filled" (default). V.1.3+ könnte via by-slug-Query
+// ermitteln ob ein Block tatsächlich body hat und „stub" markieren wenn
+// leer (Provider-Author-Hinweis dass Block existiert aber befüllt werden
+// muss). Aktuell ist legal-pages's Boot-Check der primäre Wächter für
+// fehlende Pflicht-Blocks.
+
+import type { TreeChildrenSubscribe, TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { LEGAL_OPTIONAL_BLOCKS, LEGAL_REQUIRED_BLOCKS } from "../constants";
+
+const treeProvider: TreeChildrenSubscribe = (_ctx) => (emit) => {
+  const allBlocks = [...LEGAL_REQUIRED_BLOCKS, ...LEGAL_OPTIONAL_BLOCKS];
+  const nodes: readonly TreeNode[] = allBlocks.map((b) => ({
+    label: `${b.slug} (${b.lang})`,
+    target: {
+      featureId: "text-content",
+      action: "edit",
+      args: { slug: b.slug, lang: b.lang },
+    },
+  }));
+  emit(nodes);
+  return () => {};
+};
+
+export function legalPagesClient(): ClientFeatureDefinition {
+  return {
+    name: "legal-pages",
+    treeProvider,
+  };
+}

package/src/legal-pages/web/index.ts

@@ -0,0 +1,4 @@
+// @runtime client
+// Public exports für die Browser-Seite des legal-pages Features.
+
+export { legalPagesClient } from "./client-plugin";

package/src/mail-foundation/feature.ts

@@ -134,7 +134,7 @@ export async function createTransportForTenant(
     await ctxConfig(mailFoundationFeature.exports.configKeys.provider),
     FEATURE_NAME,
     "provider",
-  ) as string;
+  ) as string; // @cast-boundary engine-payload
   if (provider.length === 0) {
     const usages = ctx.registry.getExtensionUsages("mailTransport");
     const known = usages.map((u) => u.entityName).join(", ") || "<none>";

package/src/mail-transport-smtp/feature.ts

@@ -140,12 +140,12 @@ async function buildSmtpTransport(ctx: HandlerContext, tenantId: string): Promis
     await ctxConfig(mailTransportSmtpFeature.exports.configKeys.port),
     FEATURE_NAME,
     "port",
-  ) as number;
+  ) as number; // @cast-boundary engine-payload
   const secure = requireDefined(
     await ctxConfig(mailTransportSmtpFeature.exports.configKeys.secure),
     FEATURE_NAME,
     "secure",
-  ) as boolean;
+  ) as boolean; // @cast-boundary engine-payload
   const from = requireNonEmpty(
     await ctxConfig(mailTransportSmtpFeature.exports.configKeys.from),
     FEATURE_NAME,

package/src/renderer-simple/simple-renderer.ts

@@ -38,7 +38,7 @@ export const simpleRenderer: NotificationRenderer = {
   name: "simple",
 
   async render(input) {
-    const data = input.variables as EmailTemplateData;
+    const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
 
     // Fallback: if no structured fields, use title + body as header + single text section
     const header = data.header ?? data.title;

package/src/secrets/handlers/rotate.job.ts

@@ -51,7 +51,7 @@ export type RotateJobResult = {
 };
 
 export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
-  const payload = rawPayload as RotateJobPayload;
+  const payload = rawPayload as RotateJobPayload; // @cast-boundary engine-payload
   if (!ctx.masterKeyProvider) {
     throw new InternalError({
       message:
@@ -64,7 +64,7 @@ export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> =>
       message: "[secrets:rotate] ctx.db missing — job context requires a database connection.",
     });
   }
-  const db = ctx.db as DbConnection;
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
   const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
   const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
   const deadline = payload.maxDurationMs

package/src/sessions/handlers/cleanup.job.ts

@@ -39,13 +39,13 @@ export type SessionCleanupResult = {
 };
 
 export const cleanupJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
-  const payload = rawPayload as SessionCleanupPayload;
+  const payload = rawPayload as SessionCleanupPayload; // @cast-boundary engine-payload
   if (!ctx.db) {
     throw new InternalError({
       message: "[sessions:cleanup] ctx.db missing — job context requires a database connection.",
     });
   }
-  const db = ctx.db as DbConnection;
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
 
   // Coerce-and-validate: BullMQ payloads arrive as opaque JSON, so TS types
   // don't survive. Guard before the value is interpolated into SQL.

package/src/step-dispatcher/feature.ts

@@ -0,0 +1,62 @@
+// step-dispatcher — bundled-feature that drains deferred Tier-2 step
+// requests (webhook.send, mail.send, ...) after their TX commits.
+//
+// Listens on the `kumiko:system:step.dispatch-requested` system event
+// (registry-bypassed, see append-event-core.ts SYSTEM_EVENT_PREFIX).
+// Performs the side-effect and emits `kumiko:system:step.dispatched`
+// or `kumiko:system:step.dispatch-failed` back onto the same stream so
+// the audit trail lives in the event log only — no separate status table.
+
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type MailSpec, performMailDispatch } from "./mail-runner";
+import { performWebhookDispatch, type WebhookSpec } from "./webhook-runner";
+
+export const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
+export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
+export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
+export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
+
+type DispatchRequestedPayload =
+  | {
+      readonly stepKind: "webhook.send";
+      readonly spec: WebhookSpec;
+      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
+    }
+  | {
+      readonly stepKind: "mail.send";
+      readonly spec: MailSpec;
+    };
+
+export function createStepDispatcherFeature(): FeatureDefinition {
+  return defineFeature("step-dispatcher", (r) => {
+    r.systemScope();
+
+    r.multiStreamProjection({
+      name: "step-dispatcher",
+      apply: {
+        [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
+          const payload = event.payload as DispatchRequestedPayload;
+          const result =
+            payload.stepKind === "webhook.send"
+              ? await performWebhookDispatch(payload.spec)
+              : await performMailDispatch(payload.spec);
+          if (result.ok) {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type: STEP_DISPATCHED_TYPE,
+              payload: { stepKind: payload.stepKind, status: result.status },
+            });
+          } else {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type: STEP_DISPATCH_FAILED_TYPE,
+              payload: { stepKind: payload.stepKind, error: result.error, attempt: 1 },
+            });
+          }
+        },
+      },
+    });
+  });
+}

package/src/step-dispatcher/index.ts

@@ -0,0 +1,16 @@
+export { createStepDispatcherFeature, STEP_DISPATCH_AGGREGATE_TYPE } from "./feature";
+export {
+  type MailDispatchResult,
+  type MailSpec,
+  mailSpecSchema,
+  performMailDispatch,
+  setMailRunner,
+} from "./mail-runner";
+export {
+  performWebhookDispatch,
+  setWebhookFetch,
+  setWebhookSecretResolver,
+  type WebhookDispatchResult,
+  type WebhookSpec,
+  webhookSpecSchema,
+} from "./webhook-runner";

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

@@ -0,0 +1,32 @@
+// Mail execution logic — separated from feature.ts and tests-injectable.
+// Production wiring (mail-foundation transport) is a follow-up; the
+// default impl throws so a missing setMailRunner is loud, not silent.
+
+import { z } from "zod";
+
+export const mailSpecSchema = z.object({
+  to: z.union([z.string(), z.array(z.string())]),
+  subject: z.string(),
+  body: z.string(),
+  from: z.string().optional(),
+});
+
+export type MailSpec = z.infer<typeof mailSpecSchema>;
+
+export type MailDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+let mailRunner: (spec: MailSpec) => Promise<MailDispatchResult> = async () => ({
+  ok: false,
+  error:
+    "no mail-runner configured — call setMailRunner() with a mail-foundation transport adapter",
+});
+
+export function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult>): void {
+  mailRunner = fn;
+}
+
+export async function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult> {
+  return mailRunner(spec);
+}