@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.3.0

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

@@ -0,0 +1,57 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { parseRetentionOverrideOrNull } from "../_internal/parse-override";
+import { type EffectiveRetentionPolicy, resolveRetentionPolicy } from "../resolver";
+import { tenantRetentionOverrideTable } from "../schema/tenant-retention-override";
+
+// retention:query:policy-for — Cross-Feature-API fuer den Forget-Flow.
+//
+// user-data-rights-Sprint-2.U5 ruft das pro Entity um zu wissen ob ein
+// Forget mit "delete" oder "anonymize" oder "blockDelete-bis-Frist"
+// laufen soll. Plus Cleanup-Job-Sprint-2.D2b fuer das gleiche.
+//
+// Tenant-Preset-Storage existiert noch nicht (kommt mit S2.D2b ueber
+// einen tenant-config-key). Bis dahin tenantPreset=null — der Resolver
+// liefert dann nur die Entity-Default-Layer + Override.
+//
+// access: openToAll — andere Features im selben Tenant duerfen das
+// abrufen. Keine PII im Result, nur Policy-Metadata.
+export const policyForQuery = defineQueryHandler({
+  name: "policy-for",
+  schema: z.object({
+    entityName: z.string().min(1).max(100),
+  }),
+  access: { openToAll: true },
+  handler: async (query, ctx): Promise<EffectiveRetentionPolicy> => {
+    const entityName = query.payload.entityName;
+
+    // Layer 3: Tenant-Override aus DB laden (UNIQUE(tenantId, entityName))
+    const overrideRow = (await fetchOne(
+      ctx.db,
+      tenantRetentionOverrideTable,
+      eq(tenantRetentionOverrideTable["tenantId"], query.user.tenantId),
+      eq(tenantRetentionOverrideTable["entityName"], entityName),
+    )) as { config: string | null } | null; // @cast-boundary db-runner
+
+    const tenantOverride = parseRetentionOverrideOrNull(
+      overrideRow?.config ?? null,
+      query.user.tenantId,
+      "data-retention:policy-for",
+    );
+
+    // Layer 1: Entity-Default aus Registry
+    const entityDef = ctx.registry?.getEntity(entityName) ?? null;
+
+    // Layer 2: Tenant-Preset — Storage kommt mit S2.D2b. Bis dahin null.
+    const tenantPreset = null;
+
+    return resolveRetentionPolicy({
+      entityName,
+      entityDef,
+      tenantPreset,
+      tenantOverride,
+    });
+  },
+});

package/src/data-retention/index.ts

@@ -0,0 +1,18 @@
+export type {
+  EffectiveRetentionPolicy,
+  ResolveForTenantArgs,
+  ResolveRetentionPolicyArgs,
+  RetentionOverride,
+  RetentionPreset,
+  RetentionPresetKey,
+} from "./feature";
+export {
+  createDataRetentionFeature,
+  RETENTION_PRESETS,
+  resolveRetentionPolicy,
+  resolveRetentionPolicyForTenant,
+  retentionOverrideSchema,
+  SELECTABLE_RETENTION_PRESETS,
+  tenantRetentionOverrideEntity,
+  tenantRetentionOverrideTable,
+} from "./feature";

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

@@ -0,0 +1,75 @@
+// keepFor-Format-Parser: "30d" / "10y" / "6m" / "1w" / "24h" → Cutoff-Instant.
+//
+// Nicht millisekunden-praezise — DSGVO-Aufbewahrungspflichten haben
+// Tag-/Monat-Granularitaet. "6m" = 6×30d, "10y" = 10×365d. Cleanup-Job
+// laeuft taeglich, ein paar Tage Differenz beim Cutoff sind akzeptabel.
+//
+// Boot-Validator (S0.2) hat das Format schon gegen /^\d+[hdwmy]$/
+// gecheckt — hier defensiv nochmal validiert fuer Migration-Edge-Cases.
+//
+// Temporal kommt via globalThis (Polyfill in framework-Boot installiert).
+// `getTemporal()` aus framework/time gibt typed Zugriff.
+
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+
+const KEEP_FOR_PATTERN = /^(\d+)([hdwmy])$/;
+
+const UNIT_TO_DAYS: Readonly<Record<string, number>> = {
+  d: 1,
+  w: 7,
+  m: 30,
+  y: 365,
+} satisfies Readonly<Record<string, number>>;
+
+export class InvalidKeepForError extends Error {
+  constructor(spec: string) {
+    super(
+      `Invalid keepFor format "${spec}" — expected /^\\d+[hdwmy]$/ (e.g. "30d", "10y", "6m", "1w", "24h")`,
+    );
+  }
+}
+
+// Re-export von Temporal.Instant als Type-Alias damit Caller den Type
+// nicht selbst aus globalThis ziehen muessen.
+export type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+/**
+ * Berechnet den Cutoff-Instant — Rows mit reference < cutoff sind
+ * abgelaufen und werden vom Cleanup-Job geraeumt.
+ *
+ * @param spec keepFor-String wie "30d", "10y", "6m", "1w", "24h"
+ * @param now Aktueller Zeitpunkt (advisor-Pattern: injection-Parameter
+ *            fuer Time-Travel-Tests, kein global Temporal.Now)
+ */
+export function computeCutoff(spec: string, now: Instant): Instant {
+  const match = KEEP_FOR_PATTERN.exec(spec);
+  if (!match) {
+    throw new InvalidKeepForError(spec);
+  }
+  const amount = Number.parseInt(match[1] ?? "0", 10);
+  const unit = match[2] ?? "";
+
+  if (unit === "h") {
+    return now.subtract({ hours: amount });
+  }
+
+  const daysFactor = UNIT_TO_DAYS[unit];
+  if (daysFactor === undefined) {
+    throw new InvalidKeepForError(spec);
+  }
+  return now.subtract({ hours: amount * daysFactor * 24 });
+}
+
+/**
+ * Ist referenceTimestamp aelter als der keepFor-Cutoff bei now?
+ * Cleanup-Job nutzt das pro Row.
+ */
+export function isPastCutoff(args: {
+  readonly referenceTimestamp: Instant;
+  readonly keepFor: string;
+  readonly now: Instant;
+}): boolean {
+  const T = getTemporal();
+  const cutoff = computeCutoff(args.keepFor, args.now);
+  return T.Instant.compare(args.referenceTimestamp, cutoff) < 0;
+}

package/src/data-retention/override-schema.ts

@@ -0,0 +1,37 @@
+// Zod-Schema fuer RetentionOverride mit .strict() — Sprint 2.D2.5 (M2+M3).
+//
+// Symmetrisch zu compliance-profiles override-schema.ts (S1.9 Z3).
+// Sub-Sprint-Pattern (advisor-pinned): bei jedem User-konfigurierbarem
+// JSON-Override → strict-Zod + enum-validated.
+//
+// Schuetzt vor:
+//   - Top-Level-Tippfehler ("keepfor" statt "keepFor") — strict()-Reject
+//   - Strategy-Enum-Drift ("delete" statt "hardDelete") — z.enum-Reject
+//   - keepFor-Format-Drift ("30days" statt "30d") — regex-Reject
+//
+// Tenant-Override darf alle drei Properties weglassen (Resolver
+// fallback auf Preset/Entity-Default), aber WAS gesetzt ist muss
+// gueltig sein.
+
+import { z } from "zod";
+
+const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
+
+const retentionStrategySchema = z.enum(["hardDelete", "softDelete", "anonymize", "blockDelete"]);
+
+/**
+ * RetentionOverride-Zod-Schema mit .strict() — fuer (a) set-override-
+ * Handler-Validation (S2.D3) und (b) DB-Loader im Cleanup-Job (S2.D2b)
+ * der invalides JSON aus der config-Spalte loggt + skipt statt mit
+ * undefined behavior weiterzumachen.
+ */
+export const retentionOverrideSchema = z
+  .object({
+    keepFor: z
+      .string()
+      .regex(KEEP_FOR_PATTERN, "keepFor must match /^\\d+[hdwmy]$/ (e.g. '30d', '10y', '6m')")
+      .optional(),
+    strategy: retentionStrategySchema.optional(),
+    reference: z.string().min(1).optional(),
+  })
+  .strict();

package/src/data-retention/presets.ts

@@ -0,0 +1,72 @@
+// Retention-Presets — vorgefertigte Bündel von per-Entity-Aufbewahrungs-
+// Konfigurationen pro Compliance-Regime. Tenant-Admin wählt EINES (analog
+// zu compliance-profiles); Entity-Default + Tenant-Override liegen als
+// Schichten 1+3 darüber (siehe resolver.ts).
+//
+// Plan-Roadmap docs/plans/datenschutz/core-data-retention.md hat 8 Presets
+// vorgeschlagen. Sprint-2-MVP: 3 Production-Presets + 1 dev-Default,
+// rest folgt on-demand wenn Customer fragt.
+//
+// Presets sind pure Daten — keine Logik. Erweitern = Constant erweitern,
+// kein Code-Eingriff.
+
+import type { RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
+
+/**
+ * Pro Entity-Name gemappte Retention-Policy. Entity-Namen sind der
+ * String aus r.entity("name", ...) — kebab-case oder lowercase.
+ * Cleanup-Job iteriert alle bekannten Entities; was nicht im Preset
+ * steht, fällt auf Entity-Default (Layer 1) zurück.
+ */
+export type RetentionPreset = Readonly<Record<string, RetentionDef>>;
+
+export type RetentionPresetKey = "default" | "dsgvo-basic" | "dsgvo-hgb" | "swiss-dsg";
+
+/**
+ * MVP-Set für Sprint 2. Erweiterungen (hipaa, ccpa, aggressive-gdpr,
+ * pipeda-default, ca-quebec-l25) kommen on-demand.
+ */
+export const RETENTION_PRESETS: Readonly<Record<RetentionPresetKey, RetentionPreset>> = {
+  // Default — keine Auto-Aktion. Nur sinnvoll für Dev/Staging.
+  // Production-Tenant der "default" stehen lässt → Cleanup-Job
+  // schreibt Audit-Eintrag "skipped: no preset selected".
+  default: {},
+
+  // DSGVO Basic — Datenminimierung ohne Buchhaltungspflichten.
+  "dsgvo-basic": {
+    auditLog: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
+    session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
+    httpLog: { keepFor: "90d", strategy: "hardDelete", reference: "createdAt" },
+  },
+
+  // DSGVO + HGB — deutsche Aufbewahrungspflichten überlagert. Order
+  // wird anonymisiert (PII raus, Geschäftsdaten bleiben), Invoice +
+  // Booking sind blockDelete bis 10 Jahre, dann Anonymize.
+  "dsgvo-hgb": {
+    auditLog: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
+    session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
+    httpLog: { keepFor: "90d", strategy: "hardDelete", reference: "createdAt" },
+    invoice: { keepFor: "10y", strategy: "blockDelete", reference: "createdAt" },
+    booking: { keepFor: "10y", strategy: "blockDelete", reference: "createdAt" },
+    contract: { keepFor: "6y", strategy: "blockDelete", reference: "createdAt" },
+    order: { keepFor: "6y", strategy: "anonymize", reference: "completedAt" },
+  },
+
+  // Schweizer DSG — ähnlich DSGVO mit OR Art. 958f Aufbewahrung.
+  "swiss-dsg": {
+    auditLog: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
+    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-
+ * Edge-Case und wird nicht angezeigt — Production-Tenants wählen ein
+ * echtes Preset.
+ */
+export const SELECTABLE_RETENTION_PRESETS: readonly RetentionPresetKey[] = [
+  "dsgvo-basic",
+  "dsgvo-hgb",
+  "swiss-dsg",
+];

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

@@ -0,0 +1,50 @@
+// Direkter Resolver-Helper fuer Bulk-Iteration (S2.U5b Cleanup-Runner).
+//
+// `policy-for` Query (handlers/policy-for.query.ts) ist die Cross-Feature-
+// API fuer einzelne Lookups. Der Cleanup-Runner iteriert N Entities × M
+// Tenants — Handler-Roundtrip pro Lookup waere zu teuer + braucht einen
+// HandlerContext. Beide Pfade nutzen denselben `parseRetentionOverrideOrNull`
+// + `resolveRetentionPolicy`, also kein Drift-Risiko.
+
+import { type DbRunner, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { parseRetentionOverrideOrNull } from "./_internal/parse-override";
+import { type EffectiveRetentionPolicy, resolveRetentionPolicy } from "./resolver";
+import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override";
+
+export interface ResolveForTenantArgs {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+  readonly entityName: string;
+}
+
+export async function resolveRetentionPolicyForTenant(
+  args: ResolveForTenantArgs,
+): Promise<EffectiveRetentionPolicy> {
+  const overrideRow = (await fetchOne(
+    args.db,
+    tenantRetentionOverrideTable,
+    eq(tenantRetentionOverrideTable["tenantId"], args.tenantId),
+    eq(tenantRetentionOverrideTable["entityName"], args.entityName),
+  )) as { config: string | null } | null; // @cast-boundary db-runner
+
+  const tenantOverride = parseRetentionOverrideOrNull(
+    overrideRow?.config ?? null,
+    args.tenantId,
+    "data-retention:resolve-for-tenant",
+  );
+
+  const entityDef = args.registry.getEntity(args.entityName) ?? null;
+
+  // Layer 2 (Tenant-Preset) kommt mit S2.D2b. Bis dahin null.
+  const tenantPreset = null;
+
+  return resolveRetentionPolicy({
+    entityName: args.entityName,
+    entityDef,
+    tenantPreset,
+    tenantOverride,
+  });
+}

package/src/data-retention/resolver.ts

@@ -0,0 +1,107 @@
+// 3-Schicht-Retention-Resolver.
+//
+// Layer 1: Entity-Default       — Feature-Author setzt r.entity({retention})
+// Layer 2: Tenant-Preset        — Tenant-Admin wählt Bundle (RETENTION_PRESETS)
+// Layer 3: Tenant-Override      — per (tenantId, entityName) JSON-Override
+//
+// Resolver-Reihenfolge:
+//   effective = override(tenantId, entityName)
+//             ?? preset[tenant.retentionPreset][entityName]
+//             ?? entity.retention   (Code-Default aus EntityDefinition)
+//             ?? null               (keine Auto-Aktion)
+//
+// Cleanup-Job in S2.D2 ruft das pro (tenantId, entityName) und
+// entscheidet was zu tun ist (hardDelete / softDelete / anonymize /
+// blockDelete-mit-Frist-Check).
+//
+// Cross-Feature-API r.exposesApi("retention.policyFor") (S2.D3)
+// macht das aus user-data-rights heraus konsumierbar — Forget-Flow
+// fragt blockDelete-Felder ab + anonymisiert sie statt zu löschen.
+
+import type { EntityDefinition, RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
+import { RETENTION_PRESETS, type RetentionPresetKey } from "./presets";
+
+/**
+ * Roh-Override aus der DB-Tabelle (config-Spalte als JSON-String).
+ * Nicht das gleiche wie RetentionDef weil hier alles optional ist —
+ * Override darf einzelne Properties überschreiben.
+ */
+export interface RetentionOverride {
+  readonly keepFor?: string;
+  readonly strategy?: RetentionDef["strategy"];
+  readonly reference?: string;
+}
+
+/**
+ * Effektive Policy nach Resolver-Lauf. Source dokumentiert WELCHE
+ * Schicht den Wert geliefert hat — Audit-Trail für DPO.
+ *
+ * `override-incomplete` bedeutet: Tenant-Override ist gesetzt, aber
+ * füllt keepFor weder selbst noch via Preset-/Entity-Fallback.
+ * Cleanup-Job logt eine Warning + skippt — anstatt mit Default-"0d"
+ * sofort alles zu löschen.
+ */
+export interface EffectiveRetentionPolicy {
+  readonly entityName: string;
+  readonly policy: RetentionDef | null;
+  readonly source: "override" | "preset" | "entity-default" | "none" | "override-incomplete";
+}
+
+export interface ResolveRetentionPolicyArgs {
+  readonly entityName: string;
+  readonly entityDef: EntityDefinition | null;
+  readonly tenantPreset: RetentionPresetKey | null;
+  readonly tenantOverride: RetentionOverride | null;
+}
+
+/**
+ * Auswertung der drei Schichten. Pure Function — kein DB-Access, alle
+ * Inputs werden vom Caller besorgt (Cleanup-Job aggregiert pro Tenant
+ * vorher).
+ */
+export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): EffectiveRetentionPolicy {
+  const { entityName, entityDef, tenantPreset, tenantOverride } = args;
+
+  // Layer 3: Override wins, aber Override darf Felder weglassen — dann
+  // fallen die einzelnen Properties auf Layer 2/1 zurück.
+  if (tenantOverride !== null) {
+    const baseFromPreset =
+      tenantPreset !== null ? (RETENTION_PRESETS[tenantPreset]?.[entityName] ?? null) : null;
+    const baseFromEntity = entityDef?.retention ?? null;
+    const base = baseFromPreset ?? baseFromEntity;
+
+    const keepFor = tenantOverride.keepFor ?? base?.keepFor;
+    const strategy = tenantOverride.strategy ?? base?.strategy;
+
+    // keepFor + strategy sind Pflicht für jede aktive Policy. Wenn
+    // weder Override noch Base sie liefert, ist das Override semantisch
+    // unvollständig — Cleanup-Job soll WARNEN statt mit Default-"0d"
+    // sofort alles löschen. Source-Marker dokumentiert das.
+    if (keepFor === undefined || strategy === undefined) {
+      return { entityName, policy: null, source: "override-incomplete" };
+    }
+
+    const merged: RetentionDef = {
+      keepFor,
+      strategy,
+      reference: tenantOverride.reference ?? base?.reference,
+    };
+    return { entityName, policy: merged, source: "override" };
+  }
+
+  // Layer 2: Preset
+  if (tenantPreset !== null) {
+    const fromPreset = RETENTION_PRESETS[tenantPreset]?.[entityName];
+    if (fromPreset) {
+      return { entityName, policy: fromPreset, source: "preset" };
+    }
+  }
+
+  // Layer 1: Entity-Default
+  if (entityDef?.retention) {
+    return { entityName, policy: entityDef.retention, source: "entity-default" };
+  }
+
+  // Nichts da — Cleanup-Job überspringt diese Entity für diesen Tenant.
+  return { entityName, policy: null, source: "none" };
+}

package/src/data-retention/schema/tenant-retention-override.ts

@@ -0,0 +1,47 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createLongTextField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// tenantRetentionOverride — Layer 3 im 3-Schicht-Resolver.
+//
+// Per (tenantId, entityName) eine optionale Override-Config die das
+// Preset (Layer 2) für genau diese eine Entity überschreibt. Use-Cases:
+//   - Anwaltskanzlei in DE: caseFile 6y blockDelete (nicht im Preset)
+//   - Pilot-Tenant der länger speichert für Test
+//   - Branchenspezifische verkürzte Fristen
+//
+// reason ist Pflicht — Audit für DPO + Aufsichtsbehörde nachvollziehbar.
+//
+// config ist JSON-String mit `{ keepFor, strategy, reference? }`. Zod-
+// Schema validiert beim set-override-Call (S2.D2 ggf. erweitert).
+//
+// Tenant-1-zu-N: pro Tenant beliebig viele Entity-Overrides. UNIQUE-
+// Index auf (tenantId, entityName) damit pro Entity max ein Override.
+export const tenantRetentionOverrideEntity = createEntity({
+  table: "read_tenant_retention_overrides",
+  fields: {
+    entityName: createTextField({
+      required: true,
+      maxLength: 100,
+      allowPlaintext: "is-business-data",
+    }),
+    config: createLongTextField({
+      required: true,
+      allowPlaintext: "is-business-data",
+    }),
+    reason: createTextField({
+      required: true,
+      maxLength: 500,
+      allowPlaintext: "is-business-data",
+    }),
+  },
+  indexes: [{ unique: true, columns: ["tenantId", "entityName"] }],
+});
+
+export const tenantRetentionOverrideTable = buildDrizzleTable(
+  "tenantRetentionOverride",
+  tenantRetentionOverrideEntity,
+);

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

@@ -24,9 +24,10 @@
 import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   access,
+  type ConfigAccessor,
   createTenantConfig,
   defineFeature,
-  type HandlerContext,
+  type Registry,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
 
@@ -36,13 +37,52 @@ const FEATURE_NAME = "file-foundation";
 // Plugin-Interface — what a Provider-Plugin must implement
 // =============================================================================
 
+/**
+ * Schmaler Surface-Type fuer Provider-Plugins. HandlerContext ist zu
+ * fett (haelt tx, actor, signal etc.) — Provider sollen sich auf die
+ * read-Felder beschraenken die fuer Tenant-Config + Secret-Lookup
+ * gebraucht werden.
+ *
+ * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job) gibt
+ * es keinen request-bezogenen `tx`/`actor`/`signal`. Wenn ein Provider
+ * `ctx.tx` lesen wuerde, wuerde der ganze Worker-Pfad zur Runtime
+ * brechen — und das wuerde NUR mit S3 und nur in production auffallen.
+ * Die schmale Surface zwingt Provider zur expliziten Erweiterung
+ * (extra-arg) statt silent ctx-feld-ausnutzen.
+ *
+ * **Felder:**
+ *   config  — fuer tenant-config-reads (bucket/region/endpoint/...)
+ *   registry — fuer extension-Lookup in der Factory (nicht Plugin-intern)
+ *   secrets — fuer tenant-secret-reads (s3.secretAccessKey)
+ *   _userId — Audit-Identity fuer secret-reads. Im Handler-Pfad setzt
+ *             der dispatcher das auf die Caller-User-ID; im Worker-Pfad
+ *             muss der r.job-Wrap das explizit auf eine System-Identity
+ *             setzen (z.B. "system:user-data-rights:run-export-jobs").
+ */
+export type FileProviderContext = {
+  readonly config?: ConfigAccessor;
+  readonly registry?: Registry;
+  readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
+  readonly _userId?: string | undefined;
+};
+
 /**
  * File-Storage-Plugin contract. Each provider-feature (file-provider-s3,
  * file-provider-azure-blob, ...) registers an implementation via
  * `r.useExtension("fileProvider", "<name>", { build })`.
+ *
+ * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein FileProviderContext,
+ * nicht ein voller HandlerContext. Felder ausserhalb der schmalen
+ * Surface (z.B. `ctx.tx`, `ctx.actor`, `ctx.signal`, `ctx.notify`) sind
+ * im Worker-Pfad (r.job-getriggerte Provider-Builds) NICHT vorhanden.
+ * Cast `ctx as unknown as HandlerContext` macht den Compiler happy aber
+ * fliegt zur Runtime im Worker — und der Crash kommt erst in production
+ * mit dem ersten S3-Tenant. Wenn ein Plugin Felder braucht die nicht in
+ * FileProviderContext sind: lieber FileProviderContext explizit erweitern
+ * (sichtbarer breaking change) als ctx-cast.
  */
 export type FileProviderPlugin = {
-  readonly build: (ctx: HandlerContext, tenantId: string) => Promise<FileStorageProvider>;
+  readonly build: (ctx: FileProviderContext, tenantId: string) => Promise<FileStorageProvider>;
 };
 
 // =============================================================================
@@ -77,7 +117,7 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
 // =============================================================================
 
 export async function createFileProviderForTenant(
-  ctx: HandlerContext,
+  ctx: FileProviderContext,
   tenantId: string,
   handlerName = "file-foundation:provider-factory",
 ): Promise<FileStorageProvider> {
@@ -97,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-foundation/index.ts

@@ -2,6 +2,7 @@
 
 export {
   createFileProviderForTenant,
+  type FileProviderContext,
   type FileProviderPlugin,
   fileFoundationFeature,
 } from "./feature";