@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.3.0

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

@@ -17,8 +17,11 @@
 // **NICHT für Production.** Buffer ist Process-Memory, geht beim
 // Restart verloren + wächst monoton mit jedem write.
 
-import type { FileProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
-import { defineFeature, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createInMemoryFileProvider,
   type FileStorageProvider,
@@ -63,7 +66,7 @@ export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
   r.requires("file-foundation");
 
   const plugin: FileProviderPlugin = {
-    build: async (_ctx: HandlerContext, tenantId: string): Promise<FileStorageProvider> => {
+    build: async (_ctx: FileProviderContext, tenantId: string): Promise<FileStorageProvider> => {
       // Returnt den per-tenant Storage. Identitätsstabil zwischen calls
       // damit accumulated state erhalten bleibt.
       return getOrCreateProviderForTenant(tenantId);

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

@@ -18,19 +18,17 @@
 //
 // **Boot-Dependencies:** config + secrets + file-foundation.
 
-import type { FileProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import type {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
 import { createS3Provider } from "@cosmicdrift/kumiko-bundled-features/files-provider-s3";
 import {
   requireDefined,
   requireNonEmpty,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import {
-  access,
-  createTenantConfig,
-  defineFeature,
-  type HandlerContext,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
 
 const FEATURE_NAME = "file-provider-s3";
@@ -89,7 +87,7 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
   // Plugin-Registration. entityName "s3" ist was tenants in
   // file-foundation's `provider` config-key setzen.
   const plugin: FileProviderPlugin = {
-    build: async (ctx: HandlerContext, tenantId: string) => buildS3Provider(ctx, tenantId),
+    build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId),
   };
   r.useExtension("fileProvider", "s3", plugin);
 
@@ -104,7 +102,7 @@ export const S3_SECRET_ACCESS_KEY = fileProviderS3Feature.exports.secretAccessKe
 // =============================================================================
 
 async function buildS3Provider(
-  ctx: HandlerContext,
+  ctx: FileProviderContext,
   tenantId: string,
 ): Promise<FileStorageProvider> {
   const ctxConfig = ctx.config;
@@ -131,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,
@@ -157,7 +155,7 @@ async function buildS3Provider(
   });
 }
 
-async function readSecretAccessKey(ctx: HandlerContext, tenantId: string): Promise<string> {
+async function readSecretAccessKey(ctx: FileProviderContext, tenantId: string): Promise<string> {
   const secrets = requireSecretsContext(ctx, FEATURE_NAME);
   const branded = await secrets.get(tenantId, S3_SECRET_ACCESS_KEY);
   if (!branded) {

package/src/files/README.md

@@ -0,0 +1,50 @@
+# files
+
+Schema-Sicht der framework-internen `file_refs`-Tabelle als bundled-feature.
+Sprint-1.5 Refactor (Pre-Sprint-2).
+
+## Was es macht
+
+Deklariert `r.entity("fileRef", ...)` für die DB-Tabelle die das
+Framework via `createFileRoutes` (multipart-Upload + binary-Download)
+bewirtschaftet. Das öffnet die Tür für Cross-Feature-Hooks:
+
+- **Sprint 2** (`user-data-rights-defaults`) registriert `r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })` — Forget-Flow + Daten-Export fassen die Files automatisch an. ✅ done
+- **Sprint 5** (`tenant-lifecycle`) wird `r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })` registrieren — Tenant-Destroy löscht alle FileRefs.
+
+## Was es NICHT macht
+
+- **Keine Upload-/Download-Routes** — die bleiben in
+  `framework/src/api/server.ts` via `options.files`-Bootstrap.
+  Multipart-Form-Body und Binary-Streaming passen nicht ins Write/Query-
+  Handler-Pattern; ein Refactor zu `r.httpRoute` wäre orthogonal zu
+  diesem Sprint.
+- **Kein eigener Drizzle-Table-Build** — die `file_refs`-Tabelle
+  existiert schon in `framework/src/files/file-ref-table.ts`. Diese
+  Entity ist nur die Schema-Sicht für Cross-Feature-Hooks; Drizzle-
+  Queries laufen weiter über `fileRefsTable` aus
+  `@cosmicdrift/kumiko-framework/files`.
+
+## PII-Annotations (Sprint 0.1+0.7)
+
+```ts
+fileName    → pii: true                  (Originalname enthält oft Personen-Bezug)
+storageKey  → allowPlaintext: "is-business-data"  (interner UUID-Key)
+mimeType    → allowPlaintext: "is-business-data"
+size        → allowPlaintext: "is-business-data"
+entityType  → allowPlaintext: "is-business-data"
+entityId    → allowPlaintext: "is-business-data"
+fieldName   → allowPlaintext: "is-business-data"
+insertedAt  → kein PII-Marker (Audit-Timestamp, Framework-managed)
+insertedById → allowPlaintext: "is-business-data"  (User-Reference, kein Eigen-PII)
+```
+
+`fileName: pii: true` heißt: Sprint 3 Crypto-Shredding wird den Wert
+mit dem Author-Subject-Key encrypten (für File-INHALTE: separates
+Subject-Resolver-Pattern via `subjectField` — siehe storage-encryption.md
+Sprint 4).
+
+## Tests
+
+`__tests__/files.integration.ts` — 5 Tests die beweisen dass die Feature-
+Definition clean lädt + die PII-Markers + Tabellenname stimmen.

package/src/files/__tests__/files.integration.ts

@@ -0,0 +1,157 @@
+// files-feature integration tests (S1.5 + S1.7).
+//
+// Tests sortiert nach Verhaltens-Tiefe:
+//   1. Feature-Definition Smoke (Boot-Validation passes)
+//   2. Cross-Feature-Behavior: fileRef-Entity ist als Hook-Anker für
+//      Sprint-2-userData-Extension nutzbar
+//   3. DDL-Konsistenz: Framework-pgTable + Feature-Entity zeigen auf
+//      dieselbe Postgres-Struktur (Drift-Guard)
+//   4. Event-QN-Match: r.defineEvent + framework's fileUploadedEvent
+//      resolven zum selben QN
+
+import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { FILE_UPLOADED_EVENT_TYPE, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { getTableColumns } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createFilesFeature, fileRefEntity } from "../feature";
+
+let stack: TestStack;
+
+const feature = createFilesFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("files :: feature-definition smoke", () => {
+  test("Boot ist clean (PII-Annotations + Event-Schema valide)", async () => {
+    // setupTestStack hat das feature im beforeAll geladen — wenn Boot-
+    // Validation fehlschlägt, würde dieser Block nie laufen.
+    expect(stack).toBeDefined();
+  });
+
+  test("Tabellen-Name matched die Framework-pgTable (file_refs)", () => {
+    expect(fileRefEntity.table).toBe("file_refs");
+  });
+
+  test("fileName ist als pii: true markiert", () => {
+    const fileName = fileRefEntity.fields["fileName"] as { pii?: boolean };
+    expect(fileName.pii).toBe(true);
+  });
+});
+
+describe("files :: cross-feature behavior (F1, S1.7)", () => {
+  test("Sprint-2-Pattern: ein Consumer-Feature kann r.useExtension(EXT_USER_DATA, fileRef, ...) registrieren", async () => {
+    // Stub-Feature simuliert die Sprint-2-Semantik: extendsRegistrar
+    // (kommt aus user-data-rights) + useExtension auf fileRef.
+    const userDataProvider = defineFeature("test-user-data-provider", (r) => {
+      r.extendsRegistrar(EXT_USER_DATA, {
+        // Spec-stub — Sprint 2 wird die echten Hook-Signaturen liefern.
+      });
+    });
+
+    const consumer = defineFeature("test-files-consumer", (r) => {
+      r.requires("files", "test-user-data-provider");
+      r.useExtension(EXT_USER_DATA, "fileRef", {
+        // Stub-Hooks: in Sprint 2 werden diese die echte Forget-/Export-
+        // Logik tragen. Hier reicht: useExtension findet die fileRef-
+        // Entity in der Registry → kein Boot-Error.
+        export: async () => [],
+        delete: async () => undefined,
+      });
+    });
+
+    // Eigener Test-Stack damit dieser Sub-Test isoliert vom outer
+    // beforeAll-Stack laeuft.
+    const crossStack = await setupTestStack({
+      features: [feature, userDataProvider, consumer],
+    });
+    expect(crossStack).toBeDefined();
+    await crossStack.cleanup();
+  });
+
+  test("useExtension auf nicht-existierendes Entity wirft beim Boot", async () => {
+    const userDataProvider = defineFeature("test-user-data-provider-2", (r) => {
+      r.extendsRegistrar(EXT_USER_DATA, {});
+    });
+
+    const consumer = defineFeature("test-broken-consumer", (r) => {
+      r.requires("test-user-data-provider-2");
+      // GHOSTLY: useExtension auf "ghostEntity" gibt es nirgends.
+      r.useExtension(EXT_USER_DATA, "ghostEntity", {});
+    });
+
+    // Boot soll laufen — es ist NICHT der Job des Boot-Validators zu
+    // pruefen ob die referenced Entity existiert (Extensions sind
+    // generisch, "ghostEntity" könnte ein App-Entity in einem anderen
+    // Feature sein). Test dokumentiert das aktuelle Verhalten als
+    // Regression-Guard. Sprint 2 schaerft ggf. mit
+    // validateUserDataExtensionTargets.
+    const ghostStack = await setupTestStack({
+      features: [userDataProvider, consumer],
+    });
+    expect(ghostStack).toBeDefined();
+    await ghostStack.cleanup();
+  });
+});
+
+describe("files :: DDL-Konsistenz (M3, S1.7)", () => {
+  // Drizzle's getTableColumns liefert die typed column-map ohne den
+  // Symbol-Properties-Junk. Sauberer als Object.keys(table) das auch
+  // interne Drizzle-Symbols mitnimmt.
+  function pgColumnNames(): Set<string> {
+    return new Set(Object.keys(getTableColumns(fileRefsTable)));
+  }
+
+  test("Feature-Entity-Felder matchen die Framework-pgTable column-set", () => {
+    // Framework's fileRefsTable ist die Quelle der Wahrheit fuer die
+    // DB-Struktur. Feature-Entity ist Schema-Sicht. Beide muessen
+    // konsistent sein — sonst landet Sprint-2's userData-Hook in
+    // Drift-Hell beim Forget-Flow.
+    //
+    // Vergleich: alle Feature-Felder muessen als Spalten in der pgTable
+    // existieren (umgekehrt darf pgTable framework-managed Spalten haben
+    // wie tenantId/createdAt/updatedAt/deletedAt — die deklariert das
+    // Framework automatisch beim buildDrizzleTable-Mapping).
+    const pgColumns = pgColumnNames();
+    const featureFields = Object.keys(fileRefEntity.fields);
+
+    for (const field of featureFields) {
+      expect(
+        pgColumns.has(field),
+        `Feature-Field "${field}" fehlt in framework pgTable file_refs — Schema-Drift!`,
+      ).toBe(true);
+    }
+  });
+
+  test("Framework-pgTable hat die kritischen file_ref-Spalten (storageKey, fileName, mimeType, size)", () => {
+    const pgColumns = pgColumnNames();
+    expect(pgColumns.has("storageKey")).toBe(true);
+    expect(pgColumns.has("fileName")).toBe(true);
+    expect(pgColumns.has("mimeType")).toBe(true);
+    expect(pgColumns.has("size")).toBe(true);
+  });
+});
+
+describe("files :: event-QN-match (M4, S1.7)", () => {
+  test("framework's fileUploadedEvent.name === 'files:event:uploaded'", () => {
+    // Wenn das Framework den Event-Namen aendert, fliegt dieser Test
+    // sofort an — und der QN aus r.defineEvent("uploaded") im feature
+    // wuerde nicht mehr matchen. Drift-Guard.
+    expect(FILE_UPLOADED_EVENT_TYPE).toBe("files:event:uploaded");
+  });
+
+  test("Feature-Name 'files' + Event-Short 'uploaded' = QN 'files:event:uploaded'", () => {
+    // r.defineEvent("uploaded") in defineFeature("files", ...) resolved
+    // zu QN "files:event:uploaded" via Framework-Convention. Match
+    // garantiert dass framework's appendEvent + EventDef-Schema-
+    // Validation auf demselben QN landen.
+    const expected = `${feature.name}:event:uploaded`;
+    expect(expected).toBe(FILE_UPLOADED_EVENT_TYPE);
+  });
+});

package/src/files/feature.ts

@@ -0,0 +1,34 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { fileUploadedPayloadSchema } from "@cosmicdrift/kumiko-framework/files";
+import { fileRefEntity } from "./schema/file-ref";
+
+export { fileRefEntity } from "./schema/file-ref";
+
+// files — Schema-Sicht der framework-internen file_refs-Tabelle als
+// bundled-feature, damit Cross-Feature-Hooks (userData, tenantData) sich
+// an die "fileRef"-Entity hängen können.
+//
+// Sprint 1.5 (this commit):
+//   - r.entity("fileRef", fileRefEntity) — Schema-Surface
+//   - r.defineEvent("uploaded", schema)  — Event-Marker
+//
+// Sprint 2 (kommt):
+//   - r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })
+//
+// Sprint 5 (kommt):
+//   - r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })
+//
+// Routes bleiben framework-internal (multipart-Upload + binary-Streaming
+// passen nicht in das Handler-Pattern; siehe schema/file-ref.ts für
+// Architektur-Note).
+//
+// Sprint-1.5-Plan-Roadmap-Wille: "fileRefsTable bleibt in framework
+// (kein Daten-Move), aber r.entity('fileRef') deklariert sie für das
+// Feature." — diese Datei IST die Umsetzung.
+export function createFilesFeature(): FeatureDefinition {
+  return defineFeature("files", (r) => {
+    r.entity("fileRef", fileRefEntity);
+
+    r.defineEvent("uploaded", fileUploadedPayloadSchema);
+  });
+}

package/src/files/index.ts

@@ -0,0 +1 @@
+export { createFilesFeature, fileRefEntity } from "./feature";

package/src/files/schema/file-ref.ts

@@ -0,0 +1,58 @@
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// fileRef — Schema-Sicht der File-Metadata-Tabelle aus dem Framework.
+//
+// Architektur-Entscheidung (Sprint 1.5):
+//
+// Die DB-Tabelle `file_refs` lebt weiterhin in
+// `framework/src/files/file-ref-table.ts` als drizzle pgTable, weil
+// die Hono-Upload-/Download-Routes (`createFileRoutes` in
+// `framework/src/api/server.ts`) sie direkt nutzen. Multipart-Upload
+// und Binary-Streaming passen nicht in das Write/Query-Handler-Pattern
+// — Routes bleiben framework-internal.
+//
+// Was hier passiert: dieselbe DB-Tabelle wird zusätzlich als
+// `r.entity("fileRef")` in einem bundled-feature deklariert. Das
+// ermoeglicht:
+//   1. r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })
+//      in Sprint 2 — Forget-Flow + Daten-Export erkennen die Entity.
+//   2. r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })
+//      in Sprint 5 — Tenant-Lifecycle löscht alle FileRefs.
+//   3. Boot-Validation für PII-Annotations greift (fileName, originalName).
+//
+// Kein buildDrizzleTable hier — die Mapping-Tabelle existiert schon im
+// Framework. Drizzle-Reads in den Sprint-2+-Hooks gehen direkt über
+// `fileRefsTable` aus `@cosmicdrift/kumiko-framework/files`.
+//
+// PII-Annotations (Sprint 0.1+0.7+1.7):
+//   - fileName  → pii: true (Originalname enthält oft Personen-Bezug:
+//                "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf")
+//
+//   Andere Felder brauchen KEINE Annotation:
+//   - storageKey, mimeType, size, entityType, entityId, fieldName,
+//     insertedById → keine PII-typischen Field-Namen, PII-Heuristik
+//     greift nicht (siehe boot-validator.ts PII_DIRECT_NAME_HINTS).
+//     Ein allowPlaintext-Marker wäre Über-Annotation ohne Effekt.
+//   - insertedAt → Audit-Timestamp, framework-managed.
+//
+// Tabellenname matched die Framework-pgTable damit r.entity-Reads über
+// dieselbe Postgres-Tabelle laufen.
+export const fileRefEntity = createEntity({
+  table: "file_refs",
+  fields: {
+    storageKey: createTextField({ required: true }),
+    fileName: createTextField({ required: true, pii: true }),
+    mimeType: createTextField({ required: true }),
+    size: createNumberField({ required: true }),
+    entityType: createTextField(),
+    entityId: createTextField(),
+    fieldName: createTextField(),
+    insertedAt: createTimestampField({ sortable: true, filterable: true }),
+    insertedById: createTextField(),
+  },
+});

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

@@ -1,3 +1,4 @@
+import { Readable } from "node:stream";
 import {
   DeleteObjectCommand,
   GetObjectCommand,
@@ -5,9 +6,45 @@ import {
   PutObjectCommand,
   S3Client,
 } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
 import { getSignedUrl as presign } from "@aws-sdk/s3-request-presigner";
 import type { FileStorageProvider, SignedUrlOptions } from "@cosmicdrift/kumiko-framework/files";
 
+// =============================================================================
+// Operator-Pflicht-Setup (Multipart-Upload-Cleanup)
+// =============================================================================
+//
+// `writeStream` nutzt @aws-sdk/lib-storage's Upload-class fuer echtes
+// multipart-streaming. S3 created dabei eine Multipart-Upload-Session mit
+// einer Upload-ID; bei normaler Completion wird sie via Complete-
+// MultipartUpload geschlossen.
+//
+// **Edge-Case bei Worker-Abort:** wenn der Export-Worker mid-write gecancelt
+// wird (Pod-Restart, K8s-OOM-Kill, Process-Signal), bleibt die Multipart-
+// Upload-Session in S3 OFFEN. S3 behaelt die bereits hochgeladenen Parts
+// und berechnet Storage-Kosten dafuer — bis sie manuell oder via Lifecycle-
+// Rule abgebrochen werden.
+//
+// **Pflicht-Operator-Setup auf jedem Bucket:**
+//
+//   {
+//     "Rules": [{
+//       "ID": "AbortIncompleteMultipartUploads",
+//       "Status": "Enabled",
+//       "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 },
+//       "Filter": {}
+//     }]
+//   }
+//
+// AWS-CLI: `aws s3api put-bucket-lifecycle-configuration --bucket <name>
+// --lifecycle-configuration file://lifecycle.json`. Hetzner Object Storage
+// + R2 + Minio supporten dieselbe Syntax.
+//
+// **Code-side abort()** fuer graceful Worker-Shutdown ist follow-up. Das
+// braucht Worker-Cancel-Semantik (AbortSignal-Propagation durch r.job),
+// die im framework noch nicht existiert. Bis dahin ist die Lifecycle-
+// Rule die einzige Garantie gegen Storage-Leakage.
+
 // Minimal config surface — everything the SDK needs, nothing framework-
 // specific. Apps wire this into `buildServer({ files: { storageProvider } })`
 // the same way they'd pass createLocalProvider in dev.
@@ -62,6 +99,33 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
       );
     },
 
+    async writeStream(key, source, options): Promise<void> {
+      // Echtes multipart-streaming via @aws-sdk/lib-storage.Upload —
+      // der Source-AsyncIterable wird chunk-weise zu S3 hochgeladen,
+      // niemals alles im Memory aggregiert. lib-storage handled
+      // automatisch chunking (5MB-Parts default), parallel-uploads
+      // (4 concurrent default), und retry bei Part-Failures.
+      //
+      // Memory-Footprint: ~5MB pro in-flight-part × 4 concurrent =
+      // ~20MB Heap-Bound, unabhaengig von der Total-Bundle-Size. Macht
+      // 1GB+ Bundles moeglich ohne OOM.
+      //
+      // Readable.from(source) adapiert AsyncIterable → node:Readable —
+      // lib-storage's Body-Type akzeptiert Web-ReadableStream + node-
+      // Readable, nicht direkt AsyncIterable. Adapter ist zero-copy.
+      const body = Readable.from(source);
+      const upload = new Upload({
+        client,
+        params: {
+          Bucket: config.bucket,
+          Key: key,
+          Body: body,
+          ...(options?.mimeType !== undefined && { ContentType: options.mimeType }),
+        },
+      });
+      await upload.done();
+    },
+
     async read(key): Promise<Uint8Array> {
       const response = await client.send(new GetObjectCommand({ Bucket: config.bucket, Key: key }));
       if (!response.Body) {
@@ -73,6 +137,31 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
       return response.Body.transformToByteArray();
     },
 
+    readStream(key): AsyncIterable<Uint8Array> {
+      // S3 GetObject.Body ist ein StreamingBlobPayloadOutputTypes — auf
+      // node ist das ein Readable-Stream der bereits AsyncIterable<Buffer>
+      // ist. Wir wrappen lazy: erst beim ersten chunk-pull wird der
+      // GetObject-Request abgesetzt. Wenn der Key nicht existiert, faellt
+      // der Error genau dort (nicht beim readStream-Aufruf) — gleiches
+      // Lazy-Verhalten wie inmemory + local.
+      return {
+        async *[Symbol.asyncIterator]() {
+          const response = await client.send(
+            new GetObjectCommand({ Bucket: config.bucket, Key: key }),
+          );
+          if (!response.Body) {
+            throw new Error(`s3_read_empty_body: ${key}`);
+          }
+          // SdkStream is AsyncIterable<Buffer> on node. Buffer extends
+          // Uint8Array; cast sichert die Surface ohne neue runtime-deps.
+          const body = response.Body as AsyncIterable<Uint8Array>; // @cast-boundary engine-bridge
+          for await (const chunk of body) {
+            yield chunk;
+          }
+        },
+      };
+    },
+
     async delete(key): Promise<void> {
       await client.send(new DeleteObjectCommand({ Bucket: config.bucket, Key: key }));
     },
@@ -85,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;