@cosmicdrift/kumiko-framework 0.2.2 → 0.2.3

package/src/engine/types/fields.ts

@@ -5,6 +5,7 @@
 // accepted at the type layer during migration: features that pass an
 // array are auto-normalized to { [role]: "all" } at registry build.
 // Long-term: string[] disappears.
+import type { SQL } from "drizzle-orm";
 import type { OwnershipMap } from "../ownership";
 
 export type FieldAccess = {
@@ -20,6 +21,76 @@ export type FieldAccess = {
 // custom projections cannot read sensitive field values. See
 // docs/plans/architecture/projections.md.
 
+// --- PII / Subject-Key Annotations (DSGVO Art. 17 — Crypto-Shredding) ---
+//
+// Felder die PII enthalten werden in Sprint 3 (crypto-shredding) mit einem
+// Subject-Schluessel encrypted gespeichert. Subject = die natuerliche Person
+// oder der Tenant der die Daten "besitzt". Loeschung erfolgt durch Vernichten
+// des Subject-Keys ("Crypto-Shredding") — der Datensatz bleibt physisch
+// (Audit-Trail bewahrt), ist aber nicht mehr entschluesselbar. Sprint 0
+// fuegt nur die Schema-Marker + Boot-Validation ein; Encrypt/Decrypt-Mechanik
+// kommt in Sprint 3.
+//
+// Drei orthogonale Markierungen:
+//   - `pii: true`              — Subject = die Entity selbst.
+//                                Beispiel: user.email gehoert User Marc.
+//   - `userOwned: { ownerField }` — Subject = der User der im genannten
+//                                Field referenziert ist.
+//                                Beispiel: comment.body gehoert
+//                                comment.authorId.
+//   - `tenantOwned: true`      — Subject = der aktuelle Tenant
+//                                (ctx.tenantId zur Schreibzeit).
+//                                Beispiel: tenantBranding.brandColor.
+//
+// `anonymize` ist die Pro-Feld-Funktion die der retention-Cleanup-Job
+// (Sprint 2) aufruft wenn die Entity-Strategy "anonymize" lautet oder die
+// `blockDelete`-Frist abgelaufen ist. Beispiel: `() => "[ANONYMIZED]"` oder
+// `() => null`.
+//
+// `allowPlaintext` unterdrueckt PII-Heuristik-Boot-Warnings fuer Felder die
+// zwar PII-Naming haben (email, name, body) aber bewusst Klartext bleiben
+// sollen — z.B. ticket.title als Geschaeftsdaten. Wert ist eine Begruendung
+// wie "is-business-data".
+//
+// `anonymize` darf sync oder async sein — der Cleanup-Job (Sprint 2)
+// awaited den Return. Async-Funktionen sind sinnvoll wenn die Anonymisierung
+// einen Lookup braucht (z.B. konsistente Pseudonyme aus separater Tabelle).
+//
+// Siehe docs/plans/datenschutz/crypto-shredding.md und docs/plans/datenschutz/roadmap.md.
+export type PiiAnnotations = {
+  readonly pii?: boolean;
+  readonly userOwned?: { readonly ownerField: string };
+  readonly tenantOwned?: boolean;
+  readonly anonymize?: () => unknown | Promise<unknown>;
+  readonly allowPlaintext?: string;
+};
+
+// --- Retention (DSGVO Art. 5(1)(e) + HGB/AO Aufbewahrungspflichten) ---
+//
+// Pro Entity definiert der Author eine Default-Retention-Policy. Tenant-
+// Admin uebersteuert sie via Compliance-Profile + Tenant-Override (Sprint 2).
+// Vier Strategien:
+//
+//   - "hardDelete"  — Row physisch weg nach `keepFor`. Logs, Sessions.
+//   - "softDelete"  — `deletedAt = now()`. Erlaubt spaetere Restore.
+//   - "anonymize"   — Felder mit `anonymize`-Funktion ueberschrieben,
+//                     Row bleibt. Order/Invoice mit gemischter PII +
+//                     Geschaeftsdaten.
+//   - "blockDelete" — Cleanup-Job ignoriert; User-Forget loest stattdessen
+//                     `anonymize` aus. Buchhaltung, Mandate, Patientenakten.
+//
+// `keepFor` ist eine Duration-String wie "30d", "10y", "6m". Parser
+// kommt im Cleanup-Job (Sprint 2). `reference` ist das Field das den
+// Lebenszeit-Anker liefert (Default: `createdAt`). Sessions z.B. nutzen
+// `lastSeenAt` damit aktive Sessions nicht weggemueht werden.
+//
+// Siehe docs/plans/features/core-data-retention.md und Sprint 2 in roadmap.md.
+export type RetentionDef = {
+  readonly keepFor: string;
+  readonly strategy: "hardDelete" | "softDelete" | "anonymize" | "blockDelete";
+  readonly reference?: string;
+};
+
 export type TextFieldDef = {
   readonly type: "text";
   readonly maxLength?: number;
@@ -40,7 +111,7 @@ export type TextFieldDef = {
    *  explizite Höhe. Search/sort/encrypt verhalten sich unverändert
    *  identisch zu single-line — nur die Render-Surface wechselt. */
   readonly multiline?: boolean | { readonly rows?: number };
-};
+} & PiiAnnotations;
 
 /**
  * Long-form text content — source-code, markdown, blog-posts, email-
@@ -74,7 +145,7 @@ export type LongTextFieldDef = {
   readonly default?: string;
   readonly access?: FieldAccess;
   readonly multiline?: boolean | { readonly rows?: number };
-};
+} & PiiAnnotations;
 
 export type BooleanFieldDef = {
   readonly type: "boolean";
@@ -95,7 +166,7 @@ export type SelectFieldDef<TOptions extends readonly string[] = readonly string[
   readonly sensitive?: boolean;
   readonly default?: TOptions[number];
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // Mehrere Werte aus einer festen Options-Liste — UI rendert als
 // Checkbox-/Multi-Select-Kontrolle. Storage: jsonb-Array<string>;
@@ -119,7 +190,7 @@ export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly st
   /** Default-Auswahl. Jeder Eintrag muss in `options` sein (Boot-Validator). */
   readonly default?: readonly TOptions[number][];
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 export type NumberFieldDef = {
   readonly type: "number";
@@ -129,7 +200,29 @@ export type NumberFieldDef = {
   readonly sensitive?: boolean;
   readonly default?: number;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
+
+/**
+ * 64-bit-Integer-Spalte fuer Audit-Counter, Byte-Sizes, Event-IDs und
+ * andere Werte die >2^31 (~2.1 Mrd) wandern koennen. Storage als
+ * Postgres `bigint`, JS-Round-trip als `number` (mode:"number" — sicher
+ * bis 2^53 ≈ 9 PB, JSON-serialisierbar). Wer >2^53 braucht (rare),
+ * nutzt einen `text`-Field mit eigenem Codec.
+ *
+ * Vorrang vor `NumberFieldDef`-(integer 32-bit-Cap, ~2.1 GB) immer dann
+ * wenn der Wert physisch ueber dieses Limit klettern kann: Bytes,
+ * Events, Counters in High-Throughput-Apps, Cumulative-Sums. Money
+ * hat dafuer den eigenen `MoneyFieldDef` (mit Currency-Spalte).
+ */
+export type BigIntFieldDef = {
+  readonly type: "bigInt";
+  readonly required?: boolean;
+  readonly sortable?: boolean;
+  readonly filterable?: boolean;
+  readonly sensitive?: boolean;
+  readonly default?: number;
+  readonly access?: FieldAccess;
+} & PiiAnnotations;
 
 export type MoneyFieldDef = {
   readonly type: "money";
@@ -207,7 +300,7 @@ export type EmbeddedFieldDef = {
   readonly sensitive?: boolean;
   readonly schema: Readonly<Record<string, EmbeddedSubFieldDef>>;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // Legacy "date" — JS-Date-Object, semantisch unklar (Wall-Clock vs Instant).
 // Für neue Felder bevorzuge:
@@ -223,7 +316,7 @@ export type DateFieldDef = {
   readonly filterable?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // UTC-Instant (Temporal.Instant). Für Ereignisse die zu einem bestimmten
 // Augenblick passieren, ohne Location-Bezug: createdAt, loginAt, actualPickupAt.
@@ -251,7 +344,7 @@ export type TimestampFieldDef = {
    *   { pickupAt: { type: "timestamp", locatedBy: "pickupTz" }, pickupTz: { type: "tz" } }
    */
   readonly locatedBy?: string;
-};
+} & PiiAnnotations;
 
 // IANA-Zonenname (z.B. "Europe/Berlin", "America/Los_Angeles").
 // Wird via `Intl.supportedValuesOf("timeZone")` validiert (kommt im
@@ -262,7 +355,7 @@ export type TzFieldDef = {
   readonly required?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 // Wall-Clock-Termin an einem Ort als ATOMARES Konzept.
 // EIN Feld in der Schema-Definition, ZWEI Spalten in der DB
@@ -289,7 +382,7 @@ export type LocatedTimestampFieldDef = {
   readonly filterable?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
-};
+} & PiiAnnotations;
 
 export type FileFieldDef = {
   readonly type: "file";
@@ -332,6 +425,7 @@ export type FieldDefinition =
   | SelectFieldDef
   | MultiSelectFieldDef
   | NumberFieldDef
+  | BigIntFieldDef
   | MoneyFieldDef
   | ReferenceFieldDef
   | EmbeddedFieldDef
@@ -380,6 +474,20 @@ export type EntityIndexDef = {
   readonly columns: readonly [string, ...string[]];
   readonly unique?: boolean;
   readonly name?: string;
+  /**
+   * Optional SQL-Fragment fuer Partial-Index — `CREATE [UNIQUE] INDEX
+   * ... WHERE <condition>`. Postgres-Pattern fuer "Index nur unter
+   * bestimmten Bedingungen", typisches Beispiel: ExportJob-Idempotency
+   * `UNIQUE(userId) WHERE status IN ('pending', 'running')`.
+   *
+   * Caller baut das Fragment via drizzle-orm `sql\`...\``-Tagged-
+   * Template. table-builder.ts emittiert `.where(def.where)` auf den
+   * Drizzle-IndexBuilder — wirkt sowohl fuer unique- als auch fuer
+   * non-unique-Indexes (PG erlaubt beides; non-unique partial nutzt
+   * man z.B. fuer scharfe BTREE-Indexes nur auf einer Status-Teilmenge
+   * statt voller Tabelle).
+   */
+  readonly where?: SQL;
 };
 
 export type FieldsMap = Readonly<Record<string, FieldDefinition>>;
@@ -419,4 +527,20 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
     readonly read?: OwnershipMap;
     readonly write?: OwnershipMap;
   };
+  /**
+   * Default-Retention-Policy fuer diese Entity. Tenant-Admin kann via
+   * Compliance-Profile + Tenant-Override (Sprint 2) uebersteuern.
+   * Cleanup-Job (Sprint 2) verarbeitet die Strategy:
+   *
+   *   - "hardDelete" → Row physisch weg nach keepFor
+   *   - "softDelete" → deletedAt = now() (mit core-soft-delete-Feature)
+   *   - "anonymize"  → Felder mit `anonymize`-Funktion ueberschrieben,
+   *                    Row bleibt
+   *   - "blockDelete" → Cleanup-Job ignoriert; User-Forget loest
+   *                     stattdessen anonymize aus. Buchhaltung, Mandate,
+   *                     Patientenakten.
+   *
+   * Siehe docs/plans/features/core-data-retention.md.
+   */
+  readonly retention?: RetentionDef;
 };

package/src/engine/types/index.ts

@@ -66,6 +66,7 @@ export type {
 } from "./feature";
 export type {
   AnyFileFieldDef,
+  BigIntFieldDef,
   BooleanFieldDef,
   DateFieldDef,
   DefaultCurrency,
@@ -85,7 +86,9 @@ export type {
   MoneyFieldDef,
   MultiSelectFieldDef,
   NumberFieldDef,
+  PiiAnnotations,
   ReferenceFieldDef,
+  RetentionDef,
   SelectFieldDef,
   TextFieldDef,
   TimestampFieldDef,

package/src/files/__tests__/read-stream.test.ts

@@ -0,0 +1,105 @@
+// Storage-Provider readStream-API (S2.U3 Atom 3c.fix).
+//
+// Pinst:
+//   - In-memory-Provider: readStream yieldet die Bytes als single-chunk,
+//     Roundtrip identisch zu write+read.
+//   - Local-Provider: readStream nutzt fs.createReadStream → mehrere
+//     chunks fuer >hwm-Files. Lazy-Fail: ENOENT trifft erst beim ersten
+//     chunk-pull, nicht beim readStream-Aufruf.
+//   - Beide Provider: missing-key throw't beim Konsum, nicht bei
+//     readStream() — gleiches Lazy-Pattern wie S3.
+//
+// readStream + writeStream sind ab Atom 3c.fix REQUIRED in der Provider-
+// Surface (kein optional). Der Type-Compiler erzwingt Implementierung,
+// kein silent runtime-throw mehr.
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { createInMemoryFileProvider } from "../in-memory-provider";
+import { createLocalProvider } from "../local-provider";
+
+async function collect(stream: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+    total += chunk.byteLength;
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+
+describe("FileStorageProvider.readStream — in-memory", () => {
+  test("readStream returnt geschriebene Bytes identisch", async () => {
+    const provider = createInMemoryFileProvider();
+    const data = new Uint8Array([1, 2, 3, 4, 5]);
+    await provider.write("test/foo.bin", data);
+
+    const result = await collect(provider.readStream("test/foo.bin"));
+    expect(Array.from(result)).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  test("missing-key throw't beim ersten chunk-pull (lazy-Pattern)", async () => {
+    const provider = createInMemoryFileProvider();
+    // readStream() selbst wirft NICHT — das Iterator-Object existiert.
+    const stream = provider.readStream("does/not/exist.bin");
+    expect(stream).toBeDefined();
+    // Erst beim Iterieren faellt der Fehler.
+    await expect(collect(stream)).rejects.toThrow(/in-memory file not found/);
+  });
+});
+
+describe("FileStorageProvider.readStream — local", () => {
+  let basePath: string;
+
+  beforeEach(async () => {
+    basePath = await mkdtemp(join(tmpdir(), "kumiko-readstream-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(basePath, { recursive: true, force: true });
+  });
+
+  test("readStream returnt geschriebene Bytes identisch", async () => {
+    const provider = createLocalProvider(basePath);
+    const data = new Uint8Array([10, 20, 30, 40, 50]);
+    await provider.write("foo.bin", data);
+
+    const result = await collect(provider.readStream("foo.bin"));
+    expect(Array.from(result)).toEqual([10, 20, 30, 40, 50]);
+  });
+
+  test("readStream chunkt grosse Files (>64KB highWaterMark)", async () => {
+    // 200KB > default highWaterMark=64KB → erwartet mind. 2 chunks.
+    const provider = createLocalProvider(basePath);
+    const big = new Uint8Array(200 * 1024);
+    for (let i = 0; i < big.length; i++) big[i] = i & 0xff;
+    await provider.write("big.bin", big);
+
+    let chunkCount = 0;
+    let totalBytes = 0;
+    for await (const chunk of provider.readStream("big.bin")) {
+      chunkCount++;
+      totalBytes += chunk.byteLength;
+    }
+    expect(chunkCount).toBeGreaterThan(1);
+    expect(totalBytes).toBe(200 * 1024);
+  });
+
+  test("ENOENT throw't beim ersten chunk-pull (lazy-Pattern)", async () => {
+    // Pinst dass readStream() selbst kein Filesystem-Lookup macht;
+    // node:fs createReadStream emittiert error event erst beim Read-
+    // Versuch. Test-Coverage matched die Inmemory-Variante.
+    const provider = createLocalProvider(basePath);
+    const stream = provider.readStream("does/not/exist.bin");
+    expect(stream).toBeDefined();
+    await expect(collect(stream)).rejects.toThrow(/ENOENT|no such file/);
+  });
+});

package/src/files/__tests__/write-stream.test.ts

@@ -0,0 +1,233 @@
+// Storage-Provider writeStream-API (S2.U3 Atom 1d).
+//
+// Pinst:
+//   - In-memory-Provider: writeStream collected chunks + macht
+//     read-Roundtrip identisch zu write(uint8array).
+//   - Local-Provider: writeStream schreibt atomar via tmp + rename,
+//     halb-fertige Stream-Bricht hinterlassen keine Garbage am Final-
+//     Pfad.
+//   - Beide Provider liefern die Bytes via read() identisch zurueck —
+//     kein chunk-Loss, kein chunk-Order-Verlust.
+//
+// AsyncIterable-source pinst die Streaming-Semantik (Caller streamt
+// chunk-fuer-chunk, Provider niemals alles im Memory).
+
+import { mkdtemp, readdir, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { createInMemoryFileProvider } from "../in-memory-provider";
+import { createLocalProvider } from "../local-provider";
+
+async function* fromChunks(chunks: Uint8Array[]): AsyncIterable<Uint8Array> {
+  for (const c of chunks) {
+    yield c;
+  }
+}
+
+async function* slowChunks(chunks: Uint8Array[], delayMs: number): AsyncIterable<Uint8Array> {
+  for (const c of chunks) {
+    await new Promise((r) => setTimeout(r, delayMs));
+    yield c;
+  }
+}
+
+describe("FileStorageProvider.writeStream — in-memory", () => {
+  test("schreibt 3 chunks + read liefert konkateniert zurueck", async () => {
+    const provider = createInMemoryFileProvider();
+    const chunks = [
+      new Uint8Array([1, 2, 3]),
+      new Uint8Array([4, 5, 6]),
+      new Uint8Array([7, 8, 9]),
+    ];
+    await provider.writeStream("test/file.bin", fromChunks(chunks));
+
+    const data = await provider.read("test/file.bin");
+    expect(Array.from(data)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+  });
+
+  test("leerer Stream → leere Datei", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.writeStream("empty.bin", fromChunks([]));
+
+    const data = await provider.read("empty.bin");
+    expect(data.byteLength).toBe(0);
+  });
+
+  test("mimeType-Option wird in der gespeicherten Entry erhalten", async () => {
+    // Kein direkter Read-Pfad fuer mimeType — wir checken via existing-
+    // Marker (write-Pfad teilt den storage-shape). Symmetrie-Test:
+    // ein write() + ein writeStream() mit gleichem key + gleichem
+    // mimeType muessen byte-identische Reads liefern.
+    const a = createInMemoryFileProvider();
+    const b = createInMemoryFileProvider();
+    const bytes = new Uint8Array([42, 43, 44]);
+
+    await a.write("k", bytes, "application/zip");
+    if (!b.writeStream) throw new Error("writeStream missing");
+    await b.writeStream("k", fromChunks([bytes]), { mimeType: "application/zip" });
+
+    expect(Array.from(await a.read("k"))).toEqual(Array.from(await b.read("k")));
+  });
+});
+
+describe("FileStorageProvider.writeStream — local-filesystem", () => {
+  let basePath: string;
+
+  beforeEach(async () => {
+    basePath = await mkdtemp(join(tmpdir(), "kumiko-write-stream-"));
+  });
+
+  afterEach(async () => {
+    await rm(basePath, { recursive: true, force: true });
+  });
+
+  test("schreibt + read roundtrip mit chunked source", async () => {
+    const provider = createLocalProvider(basePath);
+    const chunks = [new Uint8Array([10, 20, 30]), new Uint8Array([40, 50, 60])];
+    await provider.writeStream("dir/foo.bin", fromChunks(chunks));
+
+    const data = await provider.read("dir/foo.bin");
+    expect(Array.from(data)).toEqual([10, 20, 30, 40, 50, 60]);
+  });
+
+  test("legt parent-Verzeichnisse rekursiv an", async () => {
+    const provider = createLocalProvider(basePath);
+    await provider.writeStream("deeply/nested/path/file.bin", fromChunks([new Uint8Array([1])]));
+
+    const stats = await stat(join(basePath, "deeply/nested/path/file.bin"));
+    expect(stats.isFile()).toBe(true);
+  });
+
+  test("atomar: bei wirfendem Stream entsteht KEIN final-Pfad-File", async () => {
+    const provider = createLocalProvider(basePath);
+
+    async function* failingSource(): AsyncIterable<Uint8Array> {
+      yield new Uint8Array([1, 2, 3]);
+      throw new Error("synthetic mid-stream failure");
+    }
+
+    await expect(provider.writeStream("dir/half.bin", failingSource())).rejects.toThrow(
+      /synthetic mid-stream failure/,
+    );
+
+    expect(await provider.exists("dir/half.bin")).toBe(false);
+  });
+
+  test("atomar: nach Failure ist KEIN final-Pfad-File da (.tmp-Leak ist best-effort)", async () => {
+    // Echte Atomicity-Garantie: der final-Pfad ist niemals halb-fertig
+    // sichtbar. tmp-Files koennen je nach OS-Race im destroy-Pfad
+    // kurz liegen bleiben — kein Korrektheitsproblem (kein Reader
+    // sucht nach `*.tmp`-Patterns), nur Operations-Hygiene.
+    const provider = createLocalProvider(basePath);
+
+    async function* failing(): AsyncIterable<Uint8Array> {
+      yield new Uint8Array([99]);
+      throw new Error("fail");
+    }
+
+    await expect(provider.writeStream("subdir/leak-check.bin", failing())).rejects.toThrow();
+
+    // Final-Pfad ist NICHT da — das ist die harte Garantie.
+    expect(await provider.exists("subdir/leak-check.bin")).toBe(false);
+
+    // tmp-Files duerfen nicht den final-Namen haben (sonst kein Atomicity).
+    const entries = await readdir(join(basePath, "subdir"));
+    for (const entry of entries) {
+      expect(entry).not.toBe("leak-check.bin");
+    }
+  });
+
+  test("ueberschreibt existing file atomar (rename ueber bestehenden Pfad)", async () => {
+    const provider = createLocalProvider(basePath);
+
+    await provider.write("k", new Uint8Array([1, 1, 1]));
+    await provider.writeStream("k", fromChunks([new Uint8Array([2, 2, 2])]));
+
+    const data = await provider.read("k");
+    expect(Array.from(data)).toEqual([2, 2, 2]);
+  });
+});
+
+describe("FileStorageProvider.writeStream — Streaming-Property", () => {
+  // Pinst dass writeStream tatsaechlich AsyncIterable konsumiert ohne
+  // alle chunks in eine Promise.resolve(...) Array zu converten.
+  // Wenn ein Provider intern das chunks-Array sammelt, ist das fuer
+  // unsere semantischen Garantien OK — wir testen nur das Resultat.
+  // Dieser Test sichert dass der Caller ein REIN async-iterable
+  // uebergeben kann (z.B. ZIP-Stream der chunks lazy generiert).
+
+  test("Source mit Promise-delays wird korrekt verarbeitet", async () => {
+    const provider = createInMemoryFileProvider();
+
+    async function* lazySource(): AsyncIterable<Uint8Array> {
+      await new Promise((r) => setTimeout(r, 5));
+      yield new Uint8Array([1]);
+      await new Promise((r) => setTimeout(r, 5));
+      yield new Uint8Array([2]);
+      await new Promise((r) => setTimeout(r, 5));
+      yield new Uint8Array([3]);
+    }
+
+    await provider.writeStream("lazy.bin", lazySource());
+
+    const data = await provider.read("lazy.bin");
+    expect(Array.from(data)).toEqual([1, 2, 3]);
+  });
+
+  test("local-Provider streamt WAEHREND der Source yieldet (tmp-File existiert pre-completion)", async () => {
+    // Echter Streaming-Property-Test: bei langsamen Source-yields muss
+    // der local-Provider die tmp-File anfangen zu schreiben WAEHREND
+    // wir noch chunks zur Verfuegung stellen — nicht erst alle chunks
+    // collecten.
+    //
+    // Pattern: 5 chunks mit je 30ms delay zwischen yields. Wir starten
+    // writeStream + pollen alle 10ms (max 200ms) bis tmp-File auftaucht.
+    // Bei collect-then-write taucht NIE eine tmp-File auf — Test failed
+    // dann via Timeout. Poll-basiert statt time-hardcoded gibt CI-
+    // Geschwindigkeits-Toleranz; flake-frei solange total-source-time
+    // (5 × 30ms = 150ms) > poll-Granularitaet (10ms).
+    const basePath = await mkdtemp(join(tmpdir(), "kumiko-stream-prop-"));
+    try {
+      const provider = createLocalProvider(basePath);
+      const chunks = [
+        new Uint8Array([1]),
+        new Uint8Array([2]),
+        new Uint8Array([3]),
+        new Uint8Array([4]),
+        new Uint8Array([5]),
+      ];
+      const writePromise = provider.writeStream("streamed.bin", slowChunks(chunks, 30));
+
+      // Poll bis tmp existiert ODER final schon fertig (zu schneller CI).
+      let hasTmp = false;
+      let alreadyDone = false;
+      for (let i = 0; i < 20 && !hasTmp && !alreadyDone; i++) {
+        await new Promise((r) => setTimeout(r, 10));
+        const dirContents = await readdir(basePath);
+        hasTmp = dirContents.some((f) => f.endsWith(".tmp"));
+        alreadyDone = dirContents.includes("streamed.bin");
+      }
+      if (alreadyDone && !hasTmp) {
+        throw new Error(
+          "slowChunks-delay zu kurz fuer CI: writeStream war fertig bevor poll start. " +
+            "delayMs erhoehen oder chunks reduzieren.",
+        );
+      }
+      expect(hasTmp).toBe(true); // tmp existiert WAEHREND yields
+
+      // Warten auf completion
+      await writePromise;
+
+      // Nach completion: tmp ist weg, final-File ist da
+      const finalContents = await readdir(basePath);
+      expect(finalContents).toContain("streamed.bin");
+      expect(finalContents.filter((f) => f.endsWith(".tmp"))).toEqual([]);
+
+      const data = await provider.read("streamed.bin");
+      expect(Array.from(data)).toEqual([1, 2, 3, 4, 5]);
+    } finally {
+      await rm(basePath, { recursive: true, force: true });
+    }
+  });
+});