@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/src/pipeline/event-consumer-state.ts

@@ -10,7 +10,8 @@ import {
   sql,
   text,
 } from "../db/dialect";
-import { tableExists } from "../db/schema-inspection";
+import { alterTableAddColumn } from "../db/queries/test-stack";
+import { columnNamesOf, tableExists } from "../db/schema-inspection";
 import { unsafePushTables } from "../stack";
 
 // Reserved sentinel used in the instance_id column for consumers whose
@@ -72,6 +73,14 @@ export const eventConsumerStateTable = pgTable(
       .default(sql`0`),
     status: text("status").notNull().default("idle"),
     attempts: integer("attempts").notNull().default(0),
+    // Counts automatic dead→idle revivals since the last delivery that
+    // advanced the cursor (event-dispatcher.ts's cooldown re-arm, see
+    // acquireConsumerState). A poison event never advances the cursor, so
+    // this climbs to maxRearmCount and then stays dead permanently. A
+    // successful delivery resets it to 0 (proof the consumer isn't
+    // poisoned), as does a manual restartConsumer()/enableConsumer()/
+    // skipPoisonEvent() — an operator vouching the consumer is healthy.
+    rearmCount: integer("rearm_count").notNull().default(0),
     lastError: text("last_error"),
     updatedAt: instant("updated_at", { precision: 3 }).notNull().default(sql`now()`),
   },
@@ -99,7 +108,23 @@ export type ConsumerStatus = (typeof ConsumerStatuses)[keyof typeof ConsumerStat
 //
 // guard:dup-ok — intentionale Parallele zu createProjectionStateTable; symmetrische State-Tabellen by design
 export async function createEventConsumerStateTable(db: DbConnection): Promise<void> {
-  // skip: table already exists — bootstrap is called from multiple paths
-  if (await tableExists(db, "public.kumiko_event_consumers")) return;
+  // skip: table already exists — bootstrap is called from multiple paths.
+  // Still check for columns added after the table's first deploy (e.g.
+  // rearm_count) so an older DB catches up without a dedicated migration.
+  if (await tableExists(db, "public.kumiko_event_consumers")) {
+    const cols = await columnNamesOf(db, "kumiko_event_consumers");
+    if (!cols.has("rearm_count")) {
+      await alterTableAddColumn(
+        db,
+        "kumiko_event_consumers",
+        "rearm_count",
+        "integer",
+        " DEFAULT 0",
+        " NOT NULL",
+      );
+    }
+    // skip: table (+ any missing column) is already up to date
+    return;
+  }
   await unsafePushTables(db, { kumikoEventConsumers: eventConsumerStateTable });
 }

package/src/pipeline/event-dispatcher-admin.ts

@@ -34,6 +34,7 @@ function normalizeConsumerState(row: ConsumerStateRowShape): ConsumerRecoverySta
     status: row.status,
     lastProcessedEventId: row.lastProcessedEventId,
     attempts: row.attempts,
+    rearmCount: row.rearmCount,
     lastError: row.lastError,
     updatedAt: row.updatedAt,
   };
@@ -45,6 +46,7 @@ export type ConsumerRecoveryState = {
   readonly status: string;
   readonly lastProcessedEventId: bigint;
   readonly attempts: number;
+  readonly rearmCount: number;
   readonly lastError: string | null;
   readonly updatedAt: Temporal.Instant;
 };
@@ -170,6 +172,7 @@ export async function getConsumerState(
   readonly status: string;
   readonly lastProcessedEventId: bigint;
   readonly attempts: number;
+  readonly rearmCount: number;
   readonly lastError: string | null;
   readonly updatedAt: Temporal.Instant;
 } | null> {
@@ -184,6 +187,7 @@ export async function getConsumerState(
     status: row.status,
     lastProcessedEventId: row.lastProcessedEventId,
     attempts: row.attempts,
+    rearmCount: row.rearmCount,
     lastError: row.lastError,
     updatedAt: row.updatedAt,
   };

package/src/pipeline/event-dispatcher-delivery.ts

@@ -3,6 +3,7 @@ import type { DbConnection, DbTx } from "../db/connection";
 import {
   insertConsumerIfAbsent,
   markConsumerProcessing,
+  rearmDeadConsumer,
   selectConsumerForUpdateSkipLocked,
   updateConsumerDeliveryOutcome,
 } from "../db/queries/event-consumer";
@@ -38,12 +39,13 @@ export type ConsumerStateRowShape = {
   readonly lastProcessedEventId: bigint;
   readonly status: string;
   readonly attempts: number;
+  readonly rearmCount: number;
   readonly lastError: string | null;
   readonly updatedAt: Temporal.Instant;
 };
 export type ConsumerStateRow = ConsumerStateRowShape;
 
-type StoredEventRow = {
+export type StoredEventRow = {
   readonly id: bigint;
   readonly aggregateId: string;
   readonly aggregateType: string;
@@ -80,6 +82,8 @@ export async function acquireConsumerState(
   tx: DbTx,
   name: string,
   instanceId: string,
+  rearmCooldownMs: number,
+  maxRearmCount: number,
 ): Promise<AcquireOutcome> {
   const rawState = await selectConsumerForUpdateSkipLocked(tx, name, instanceId);
 
@@ -100,7 +104,28 @@ export async function acquireConsumerState(
   }
 
   if (state.status === ConsumerStatuses.disabled) return { state: null, skip: "disabled" };
-  if (state.status === ConsumerStatuses.dead) return { state: null, skip: "dead" };
+  if (state.status === ConsumerStatuses.dead) {
+    // Bounded auto-revival: a transient failure (e.g. a Meilisearch blip)
+    // shouldn't need an operator to notice and run restartConsumer() once
+    // the cause is long gone. Cooldown since the last write (the death or
+    // a prior re-arm) gates the retry; maxRearmCount stops a poison event
+    // from looping forever (re-arm → same event fails → dead → re-arm →
+    // ...) — after the cap it stays dead until a human intervenes.
+    const cooldownDeadline = Temporal.Now.instant().subtract({ milliseconds: rearmCooldownMs });
+    const cooldownElapsed = Temporal.Instant.compare(state.updatedAt, cooldownDeadline) <= 0;
+    if (cooldownElapsed && state.rearmCount < maxRearmCount) {
+      const rearmed = await rearmDeadConsumer(tx, name, instanceId);
+      const rearmedState =
+        rearmed &&
+        (coerceRow(rearmed, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
+      if (rearmedState) return { state: rearmedState, skip: null };
+    }
+    // ponytail: no log/metric fires when the rearm budget is exhausted here
+    // (the exact "braucht manuellen Eingriff" moment) — queryable via
+    // getConsumerState but silent otherwise. Add an emitDispatcherError-style
+    // signal if ops needs a push instead of a dead+lag poll.
+    return { state: null, skip: "dead" };
+  }
   return { state, skip: null };
 }
 
@@ -183,6 +208,7 @@ export async function deliverEvents(
   let attempts = state.attempts;
   let lastError: string | null = state.lastError ?? null;
   let deadLettered = false;
+  const effectiveMaxAttempts = consumer.errorPolicy?.maxAttempts ?? maxAttempts;
   let processed = 0;
   let failed = 0;
 
@@ -231,7 +257,7 @@ export async function deliverEvents(
       attempts += 1;
       lastError = errMessage;
       failed += 1;
-      if (attempts >= maxAttempts) deadLettered = true;
+      if (attempts >= effectiveMaxAttempts) deadLettered = true;
       break;
     }
   }

package/src/pipeline/event-dispatcher.ts

@@ -66,6 +66,11 @@ export type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Prom
 // the EventConsumer (see api/server.ts MSP wiring).
 export type EventConsumerErrorPolicy = {
   readonly skipApplyErrors?: boolean;
+  // Per-consumer override of EventDispatcherOptions.maxAttempts. A consumer
+  // that depends on infra which may still be provisioning at boot (search
+  // adapter, external APIs) needs more retry headroom than the dispatcher-
+  // wide default before it gets dead-lettered.
+  readonly maxAttempts?: number;
 };
 
 export type EventConsumer = {
@@ -129,6 +134,17 @@ export type EventDispatcherOptions = {
   readonly batchSize?: number;
   readonly pollIntervalMs?: number;
   readonly maxAttempts?: number;
+  // Bounded auto-revival of a "dead" consumer. A dead consumer whose last
+  // write is older than rearmCooldownMs gets reset to idle and retried.
+  // rearmCount tracks re-arms since the last delivery that actually
+  // advanced the cursor — a poison event never advances it, so it climbs
+  // 1→maxRearmCount and then stays dead permanently; a transient failure
+  // that later delivers successfully resets it back to 0, so an unrelated
+  // future outage gets its own fresh budget. restartConsumer()/
+  // enableConsumer()/skipPoisonEvent() also reset it (an operator vouching
+  // the consumer is healthy again).
+  readonly rearmCooldownMs?: number;
+  readonly maxRearmCount?: number;
   readonly tracer?: Tracer;
   readonly meter?: Meter;
   // Identifies THIS dispatcher process in the consumer-state table. Used as
@@ -150,6 +166,8 @@ export type EventDispatcherOptions = {
 const DEFAULT_BATCH_SIZE = 200;
 const DEFAULT_POLL_MS = 100;
 const DEFAULT_MAX_ATTEMPTS = 10;
+const DEFAULT_REARM_COOLDOWN_MS = 5 * 60_000;
+const DEFAULT_MAX_REARM_COUNT = 3;
 
 export function createEventDispatcher(options: EventDispatcherOptions): EventDispatcher {
   const {
@@ -159,6 +177,8 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
     batchSize = DEFAULT_BATCH_SIZE,
     pollIntervalMs = DEFAULT_POLL_MS,
     maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    rearmCooldownMs = DEFAULT_REARM_COOLDOWN_MS,
+    maxRearmCount = DEFAULT_MAX_REARM_COUNT,
   } = options;
 
   // Fail-fast on misconfigured per-instance wiring. Catching this at
@@ -273,7 +293,13 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
 
     try {
       await db.begin(async (tx: DbTx) => {
-        const acquired = await acquireConsumerState(tx, consumer.name, instanceId);
+        const acquired = await acquireConsumerState(
+          tx,
+          consumer.name,
+          instanceId,
+          rearmCooldownMs,
+          maxRearmCount,
+        );
         // skip: another instance holds the lock, or the consumer is
         // disabled/dead. Nothing to deliver this pass.
         if (acquired.skip !== null) {

package/src/pipeline/system-hooks.ts

@@ -41,6 +41,13 @@ export function createSearchEventConsumer(
 ): EventConsumer {
   return {
     name: SEARCH_CONSUMER_NAME,
+    // ponytail: count-based maxAttempts, not real backoff — retries hammer
+    // the search adapter every pollIntervalMs during an outage instead of
+    // spacing out. 1200 attempts * 100ms default poll ~= 2min budget for a
+    // still-provisioning Meilisearch to come up at boot (was 10 = ~1s,
+    // killing the consumer near-instantly). Upgrade path: time-based
+    // dead-lettering in event-dispatcher-delivery.ts if 2min isn't enough.
+    errorPolicy: { maxAttempts: 1200 },
     handler: async (event) => {
       const entityName = event.aggregateType;
       const verb = event.type.split(".").pop();

package/src/search/types.ts

@@ -1,39 +1 @@
-import type { EntityId, TenantId } from "../engine/types/identifiers";
-
-export type SearchAdapterConfig = {
-  searchableFields: readonly string[];
-  rankingFields?: readonly string[];
-};
-
-export type SearchDocument = {
-  entityType: string;
-  entityId: EntityId;
-  weight: number;
-  fields: Record<string, unknown>;
-};
-
-export type SearchResult = {
-  entityType: string;
-  entityId: EntityId;
-};
-
-export type SearchOptions = {
-  limit?: number;
-  filterType?: string;
-};
-
-export type SearchAdapter = {
-  configure(tenantId: TenantId, config: SearchAdapterConfig): Promise<void>;
-  index(tenantId: TenantId, doc: SearchDocument): Promise<void>;
-  search(tenantId: TenantId, query: string, options?: SearchOptions): Promise<SearchResult[]>;
-  remove(tenantId: TenantId, entityType: string, entityId: EntityId): Promise<void>;
-  // Bulk variants. Default implementations loop over the single-doc methods —
-  // adapters should override when the backend supports a real batch call
-  // (Meilisearch, Elasticsearch, Typesense all do). Cuts a batch-write from
-  // N sequential HTTP + waitTask round-trips to one.
-  indexBatch?(tenantId: TenantId, docs: readonly SearchDocument[]): Promise<void>;
-  removeBatch?(
-    tenantId: TenantId,
-    items: readonly { entityType: string; entityId: EntityId }[],
-  ): Promise<void>;
-};
+export * from "@cosmicdrift/kumiko-types/search-adapter";

package/src/secrets/__tests__/envelope-cipher.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { createEncryptionProvider } from "../../db/encryption";
 import { createEnvMasterKeyProvider } from "../env-master-key-provider";
 import { createEnvelopeCipher } from "../envelope-cipher";
 import { isStoredEnvelope } from "../stored-envelope";
@@ -42,33 +41,6 @@ describe("envelope-cipher — encrypt/decrypt", () => {
   });
 });
 
-describe("envelope-cipher — legacy fallback", () => {
-  test("decrypts legacy single-key values when the legacy provider is configured", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const legacyStored = legacy.encrypt("pre-envelope value");
-    // legacy wire format is base64 — never starts with "{"
-    expect(legacyStored.startsWith("{")).toBe(false);
-
-    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
-    expect(await cipher.decrypt(legacyStored)).toBe("pre-envelope value");
-  });
-
-  test("throws with a remediation message when a legacy value has no legacy key", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const legacyStored = legacy.encrypt("orphaned");
-
-    const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt(legacyStored)).rejects.toThrow(/legacy/);
-  });
-
-  test("never encrypts into the legacy format even when a legacy key is present", async () => {
-    const legacy = createEncryptionProvider(randomBytes(32).toString("base64"));
-    const cipher = createEnvelopeCipher(makeProvider(), { legacy });
-    const stored = await cipher.encrypt("always-envelope");
-    expect(stored.startsWith("{")).toBe(true);
-  });
-});
-
 describe("envelope-cipher — malformed input", () => {
   test("rejects invalid JSON that looks like an envelope", async () => {
     const cipher = createEnvelopeCipher(makeProvider());
@@ -80,8 +52,8 @@ describe("envelope-cipher — malformed input", () => {
     await expect(cipher.decrypt('{"foo":"bar"}')).rejects.toThrow(/not a StoredEnvelope/);
   });
 
-  test("empty string routes to the legacy branch and throws without a legacy key", async () => {
+  test("empty string is not valid JSON", async () => {
     const cipher = createEnvelopeCipher(makeProvider());
-    await expect(cipher.decrypt("")).rejects.toThrow(/legacy/);
+    await expect(cipher.decrypt("")).rejects.toThrow(/not valid JSON/);
   });
 });

package/src/secrets/__tests__/envelope.test.ts

@@ -53,7 +53,7 @@ describe("envelope — encryptValue/decryptValue", () => {
       ...envelope,
       ciphertext: Buffer.concat([
         envelope.ciphertext.subarray(0, 1),
-        Buffer.from([envelope.ciphertext[0]! ^ 0xff]),
+        Buffer.from([envelope.ciphertext[1]! ^ 0xff]),
         envelope.ciphertext.subarray(2),
       ]),
     };

package/src/secrets/envelope-cipher.ts

@@ -1,12 +1,8 @@
 // String-in/string-out envelope encryption for TEXT-column stores (config
 // values, entity fields). The stored string is JSON of StoredEnvelope; the
 // kekVersion inside makes every value rotatable via the MasterKeyProvider
-// keyring — unlike the legacy createEncryptionProvider format (raw
-// base64(iv+tag+ct), no key id), which this cipher still DECRYPTS through
-// the optional legacy provider so pre-envelope rows stay readable until a
-// re-encrypt job has migrated them.
+// keyring.
 
-import type { EncryptionProvider } from "../db/encryption";
 import { InternalError } from "../errors/classes";
 import type { DekCache } from "./dek-cache";
 import { createDekCache, withDekCache } from "./dek-cache";
@@ -15,9 +11,6 @@ import { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope } from "./
 import type { KeyScope, MasterKeyProvider } from "./types";
 
 export type EnvelopeCipherOptions = {
-  // Decrypt-only fallback for legacy createEncryptionProvider ciphertexts
-  // (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY era). Never used for encrypt.
-  readonly legacy?: EncryptionProvider;
   // Shared DEK cache — pass the app-wide instance so config/entity reads
   // amortise KEK unwraps together with ctx.secrets.
   readonly dekCache?: DekCache;
@@ -28,13 +21,6 @@ export type EnvelopeCipher = {
   decrypt(stored: string, scope?: KeyScope): Promise<string>;
 };
 
-// Format detection: envelope values are JSON objects, so they start with
-// "{" — a character the base64 alphabet of the legacy format can never
-// produce. No version byte or prefix marker needed.
-function isEnvelopeFormat(stored: string): boolean {
-  return stored.startsWith("{");
-}
-
 export function createEnvelopeCipher(
   provider: MasterKeyProvider,
   opts: EnvelopeCipherOptions = {},
@@ -48,34 +34,22 @@ export function createEnvelopeCipher(
     },
 
     async decrypt(stored, scope) {
-      if (isEnvelopeFormat(stored)) {
-        let parsed: unknown;
-        try {
-          parsed = JSON.parse(stored);
-        } catch {
-          throw new InternalError({
-            message: "[envelope-cipher] stored value looks like an envelope but is not valid JSON",
-            i18nKey: "secrets.errors.envelope_malformed",
-          });
-        }
-        if (!isStoredEnvelope(parsed)) {
-          throw new InternalError({
-            message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
-            i18nKey: "secrets.errors.envelope_malformed",
-          });
-        }
-        return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(stored);
+      } catch {
+        throw new InternalError({
+          message: "[envelope-cipher] stored value is not valid JSON",
+          i18nKey: "secrets.errors.envelope_malformed",
+        });
       }
-
-      if (!opts.legacy) {
+      if (!isStoredEnvelope(parsed)) {
         throw new InternalError({
-          message:
-            "[envelope-cipher] value is in the legacy single-key format but no legacy key is configured — " +
-            "provision the legacy key (CONFIG_ENCRYPTION_KEY / ENCRYPTION_KEY) or run the re-encrypt job first",
-          i18nKey: "secrets.errors.legacy_key_missing",
+          message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
+          i18nKey: "secrets.errors.envelope_malformed",
         });
       }
-      return opts.legacy.decrypt(stored);
+      return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
     },
   };
 }

package/src/stack/__tests__/event-collector.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import type { SseEvent } from "../../api/sse-broker";
+import type { SaveContext } from "../../engine/types";
+import { createEventCollector } from "../event-collector";
+
+const probeSseEvent: SseEvent = { type: "probe", data: {} };
+const probeSaveContext: SaveContext = {
+  kind: "save",
+  id: "e1",
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
+
+describe("createEventCollector", () => {
+  test("starts empty", () => {
+    const collector = createEventCollector();
+    expect(collector.sse).toEqual([]);
+    expect(collector.postSave).toEqual([]);
+  });
+
+  test("reset() clears both arrays in place, keeping the same references", () => {
+    const collector = createEventCollector();
+    const sseRef = collector.sse;
+    const postSaveRef = collector.postSave;
+    collector.sse.push(probeSseEvent);
+    collector.postSave.push(probeSaveContext);
+
+    expect(collector.sse).toHaveLength(1);
+    expect(collector.postSave).toHaveLength(1);
+
+    collector.reset();
+
+    expect(collector.sse).toHaveLength(0);
+    expect(collector.postSave).toHaveLength(0);
+    // Same array instances — callers that captured a reference before reset
+    // still see the cleared state, not a stale snapshot.
+    expect(collector.sse).toBe(sseRef);
+    expect(collector.postSave).toBe(postSaveRef);
+  });
+});

package/src/testing/__tests__/late-bound.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { createLateBoundHolder } from "../late-bound";
+
+describe("createLateBoundHolder", () => {
+  test("isReady is false and get() throws before set()", () => {
+    const holder = createLateBoundHolder<number>("thing");
+    expect(holder.isReady()).toBe(false);
+    expect(() => holder.get()).toThrow(/thing accessed before set\(\) was called/);
+  });
+
+  test("get() returns the stored value after set()", () => {
+    const holder = createLateBoundHolder<{ n: number }>();
+    const value = { n: 42 };
+    holder.set(value);
+    expect(holder.isReady()).toBe(true);
+    expect(holder.get()).toBe(value);
+  });
+
+  test("set() can be called again to replace the value", () => {
+    const holder = createLateBoundHolder<string>();
+    holder.set("first");
+    holder.set("second");
+    expect(holder.get()).toBe("second");
+  });
+});

package/src/testing/__tests__/wait-for.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { waitFor } from "../wait-for";
+
+describe("waitFor", () => {
+  test("returns immediately once fn succeeds on the first attempt", async () => {
+    let calls = 0;
+    await waitFor(
+      () => {
+        calls++;
+      },
+      { delays: [1, 1, 1] },
+    );
+    expect(calls).toBe(1);
+  });
+
+  test("retries on failure and succeeds once fn passes", async () => {
+    let calls = 0;
+    await waitFor(
+      () => {
+        calls++;
+        if (calls < 3) throw new Error(`not yet (${calls})`);
+      },
+      { delays: [1, 1, 1] },
+    );
+    expect(calls).toBe(3);
+  });
+
+  test("throws the last error once every attempt in the schedule fails", async () => {
+    let calls = 0;
+    await expect(
+      waitFor(
+        () => {
+          calls++;
+          throw new Error(`fail-${calls}`);
+        },
+        { delays: [1, 1] },
+      ),
+    ).rejects.toThrow("fail-2");
+    expect(calls).toBe(2);
+  });
+
+  test("supports an async fn", async () => {
+    let calls = 0;
+    await waitFor(
+      async () => {
+        calls++;
+        if (calls < 2) throw new Error("not yet");
+      },
+      { delays: [1, 1] },
+    );
+    expect(calls).toBe(2);
+  });
+});

package/src/testing/boot-validator-fixture.ts

@@ -1,11 +1,11 @@
 import { SEARCHABLE_FALSE_WHITELIST } from "../engine/boot-validator/entity-list-screens";
+import { normalizeListColumn } from "../engine/screen-helpers";
 import type {
   EntityDefinition,
   EntityListScreenDefinition,
   FeatureDefinition,
   TranslationEntry,
 } from "../engine/types";
-import { normalizeListColumn } from "../engine/types/screen";
 import { featureHasI18nSurface, requiredKeysFromFeature } from "../i18n/required-surface-keys";
 
 function ensureEntityListSortable(feature: FeatureDefinition): FeatureDefinition {

package/src/testing/file-provider-contract.ts

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { FileStorageProvider } from "../files/types";
+
+const bytes = (s: string) => new TextEncoder().encode(s);
+const decode = (u: Uint8Array) => new TextDecoder().decode(u);
+
+async function* fromChunks(chunks: Uint8Array[]): AsyncIterable<Uint8Array> {
+  for (const c of chunks) yield c;
+}
+
+// Mirrors describeKmsAdapterContract (crypto/__tests__/kms-adapter-contract.ts):
+// pins the FileStorageProvider contract against whatever implementation the
+// factory returns. Provider-specific behavior (error messages, buffer
+// copies, multipart details) stays in each provider's dedicated tests.
+export function describeFileProviderContract(
+  name: string,
+  factory: () => FileStorageProvider | Promise<FileStorageProvider>,
+): void {
+  describe(`${name} — FileStorageProvider contract`, () => {
+    let provider: FileStorageProvider;
+
+    beforeEach(async () => {
+      provider = await factory();
+    });
+
+    test("write + read roundtrip preserves bytes", async () => {
+      const key = `contract/${crypto.randomUUID()}.bin`;
+      await provider.write(key, bytes("hello contract"));
+      expect(decode(await provider.read(key))).toBe("hello contract");
+    });
+
+    test("write on an existing key overwrites it (last-write-wins)", async () => {
+      const key = `contract/${crypto.randomUUID()}.bin`;
+      await provider.write(key, bytes("first"));
+      await provider.write(key, bytes("second"));
+      expect(decode(await provider.read(key))).toBe("second");
+    });
+
+    test("read throws for a missing key", async () => {
+      await expect(provider.read(`contract/missing-${crypto.randomUUID()}`)).rejects.toThrow();
+    });
+
+    test("exists reflects write + delete", async () => {
+      const key = `contract/${crypto.randomUUID()}.txt`;
+      expect(await provider.exists(key)).toBe(false);
+      await provider.write(key, bytes("x"));
+      expect(await provider.exists(key)).toBe(true);
+      await provider.delete(key);
+      expect(await provider.exists(key)).toBe(false);
+    });
+
+    test("delete on a missing key is a no-op", async () => {
+      await expect(
+        provider.delete(`contract/never-existed-${crypto.randomUUID()}`),
+      ).resolves.toBeUndefined();
+    });
+
+    test("writeStream + readStream roundtrip preserves bytes", async () => {
+      const key = `contract/${crypto.randomUUID()}.stream`;
+      await provider.writeStream(key, fromChunks([bytes("foo"), bytes("bar")]));
+      let out = "";
+      for await (const chunk of provider.readStream(key)) out += decode(chunk);
+      expect(out).toBe("foobar");
+    });
+
+    test("readStream on a missing key throws on the first chunk pull", async () => {
+      const it = provider
+        .readStream(`contract/missing-${crypto.randomUUID()}`)
+        [Symbol.asyncIterator]();
+      await expect(it.next()).rejects.toThrow();
+    });
+
+    test("getSignedUrl, when implemented, returns a URL string", async () => {
+      // skip: getSignedUrl is optional on the contract — feature-detected
+      if (!provider.getSignedUrl) return;
+
+      const key = `contract/${crypto.randomUUID()}.txt`;
+      await provider.write(key, bytes("signed"));
+      const url = await provider.getSignedUrl(key, 60);
+      expect(typeof url).toBe("string");
+      expect(url.length).toBeGreaterThan(0);
+    });
+  });
+}

package/src/testing/handler-context.ts

@@ -117,7 +117,7 @@ export function bridgeStub(opts?: {
     ) as unknown as HandlerContext["resolveAuthClaims"],
     // Stub defaults to always-enabled — matches the dispatcher's behaviour
     // when no effectiveFeatures resolver is wired (tests without toggles).
-    hasFeature: () => true,
+    hasFeature: async () => true,
     metrics: createNoopMetricsHandle(),
     tracer: noopTracer,
     // Echter TzContext, kein notAvailable — Test-Code nutzt ctx.tz häufig

package/src/testing/index.ts

@@ -15,6 +15,7 @@ export {
   generateZodFixture,
 } from "./e2e-generator";
 export { expectErrorIncludes } from "./expect-error";
+export { describeFileProviderContract } from "./file-provider-contract";
 export { bridgeStub } from "./handler-context";
 export {
   getSetCookieRaw,