@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/secrets/envelope.js

@@ -0,0 +1,44 @@
+// Envelope encryption primitives. Combines a freshly-generated DEK + the
+// central KEK (via MasterKeyProvider) into a self-contained Envelope that
+// carries everything needed to decrypt later.
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+const ALGORITHM = "aes-256-gcm";
+const DEK_LENGTH = 32; // AES-256
+const IV_LENGTH = 12; // GCM standard nonce length
+// Encrypts plaintext with a new random DEK, then wraps the DEK with the
+// current KEK. The returned Envelope is safe to store at rest.
+export async function encryptValue(plaintext, provider, scope) {
+    // Fresh DEK per value. Reusing DEKs across rows would break forward
+    // secrecy (one compromised ciphertext-IV pair leaks information about
+    // others encrypted with the same DEK).
+    const dek = randomBytes(DEK_LENGTH);
+    try {
+        const iv = randomBytes(IV_LENGTH);
+        const cipher = createCipheriv(ALGORITHM, dek, iv);
+        const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        const { encryptedDek, kekVersion } = await provider.wrapDek(dek, scope);
+        return { ciphertext, iv, authTag, encryptedDek, kekVersion };
+    }
+    finally {
+        // Zero the DEK on best effort regardless of success — if provider.wrapDek
+        // threw, the plaintext DEK must still not linger in the heap waiting
+        // for GC. Node can't guarantee secure erase, but clearing the bytes
+        // removes the obvious window.
+        dek.fill(0);
+    }
+}
+// Decrypts an Envelope. Throws if the authTag doesn't match — tampered
+// ciphertexts cannot round-trip.
+export async function decryptValue(envelope, provider, scope) {
+    const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion, scope);
+    try {
+        const decipher = createDecipheriv(ALGORITHM, dek, envelope.iv);
+        decipher.setAuthTag(envelope.authTag);
+        const plaintext = Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]);
+        return plaintext.toString("utf8");
+    }
+    finally {
+        dek.fill(0);
+    }
+}

package/dist/secrets/index.d.ts

@@ -0,0 +1,9 @@
+export { createDekCache, type DekCache, type DekCacheOptions, withDekCache } from "./dek-cache.js";
+export { derivePurposeSecret } from "./derive-purpose-secret.js";
+export { createEnvMasterKeyProvider, type EnvMasterKeyProviderOptions, type Keyring, } from "./env-master-key-provider.js";
+export { decryptValue, encryptValue } from "./envelope.js";
+export { createEnvelopeCipher, type EnvelopeCipher, type EnvelopeCipherOptions, } from "./envelope-cipher.js";
+export { assertNoSecretLeak } from "./leak-guard.js";
+export { rewrapDek } from "./rotation.js";
+export { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope, type StoredEnvelope, } from "./stored-envelope.js";
+export { type ContainsSecret, createSecret, type Envelope, isSecret, type KeyScope, type MasterKeyProvider, type Secret, type SecretAuditContext, type SecretKeyRef, type SecretsContext, } from "./types.js";

package/dist/secrets/index.js

@@ -0,0 +1,9 @@
+export { createDekCache, withDekCache } from "./dek-cache.js";
+export { derivePurposeSecret } from "./derive-purpose-secret.js";
+export { createEnvMasterKeyProvider, } from "./env-master-key-provider.js";
+export { decryptValue, encryptValue } from "./envelope.js";
+export { createEnvelopeCipher, } from "./envelope-cipher.js";
+export { assertNoSecretLeak } from "./leak-guard.js";
+export { rewrapDek } from "./rotation.js";
+export { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope, } from "./stored-envelope.js";
+export { createSecret, isSecret, } from "./types.js";

package/dist/secrets/leak-guard.d.ts

@@ -0,0 +1 @@
+export declare function assertNoSecretLeak(value: unknown, path?: string, depth?: number): void;

package/dist/secrets/leak-guard.js

@@ -0,0 +1,79 @@
+// Response-leak guard. Walks a handler-result tree and throws the moment it
+// finds a Secret<> branded value — the dispatcher calls this after every
+// handler returns, so accidentally including a plaintext secret in the
+// response body becomes a runtime error at the handler boundary rather
+// than a silent exfiltration to the client.
+import { InternalError } from "../errors/index.js";
+import { isSecret } from "./types.js";
+// Maximum depth the walker descends. A legitimate result tree is rarely
+// deeper than a few levels; the cap is a safety net against cyclic or
+// pathologically-deep user input smuggled into a response.
+const MAX_DEPTH = 12;
+export function assertNoSecretLeak(value, path = "$", depth = 0) {
+    // skip: nothing to walk at null/undefined leaves.
+    if (value === null || value === undefined)
+        return;
+    if (isSecret(value)) {
+        throw new InternalError({
+            message: `[secrets] Secret<> leaked into response at ${path}. ` +
+                "Feature code must call .reveal() and use the plaintext in an " +
+                "external call (SMTP, HTTP header, etc.) — never return the branded " +
+                "value, even unwrapped, unless you've stripped it from the response first.",
+        });
+    }
+    // skip: hit the recursion cap. Cyclic or pathologically-deep input is
+    // more likely than a legitimate 12-level-deep secret — trade coverage
+    // for termination guarantees.
+    if (depth >= MAX_DEPTH)
+        return;
+    const t = typeof value;
+    // skip: primitives already handled by the isSecret check above — strings,
+    // numbers, booleans can't hold a brand.
+    if (t !== "object")
+        return;
+    // Map and Set get walked through their entries — a feature could legitimately
+    // build either, and a custom toJSON could expand them onto the wire.
+    // JSON.stringify-by-default produces "{}" for both, which would mask the
+    // leak silently; we'd rather throw at the boundary than rely on that
+    // accident.
+    if (value instanceof Map) {
+        let i = 0;
+        for (const [k, v] of value) {
+            assertNoSecretLeak(k, `${path}.<map[${i}].key>`, depth + 1);
+            assertNoSecretLeak(v, `${path}.<map[${i}].val>`, depth + 1);
+            i++;
+        }
+        // skip: map fully walked, nothing else at this level.
+        return;
+    }
+    if (value instanceof Set) {
+        let i = 0;
+        for (const v of value) {
+            assertNoSecretLeak(v, `${path}.<set[${i}]>`, depth + 1);
+            i++;
+        }
+        // skip: set fully walked, nothing else at this level.
+        return;
+    }
+    // Skip remaining class instances we can't introspect safely (Date, Buffer,
+    // Temporal.Instant, custom domain classes, etc.). Plain objects have
+    // Object.prototype or null prototype — that's what handler responses
+    // serialize to JSON from.
+    const proto = Object.getPrototypeOf(value);
+    // skip: non-plain object (class instance). Brand check at entry already
+    // verified it's not a Secret<>; anything else is opaque to us.
+    if (proto !== null && proto !== Object.prototype && !Array.isArray(value)) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            assertNoSecretLeak(value[i], `${path}[${i}]`, depth + 1);
+        }
+        // skip: array fully walked, nothing else at this level.
+        return;
+    }
+    const obj = value; // @cast-boundary recursive-walk
+    for (const [k, v] of Object.entries(obj)) {
+        assertNoSecretLeak(v, `${path}.${k}`, depth + 1);
+    }
+}

package/dist/secrets/rotation.d.ts

@@ -0,0 +1,2 @@
+import type { Envelope, MasterKeyProvider } from "./types.js";
+export declare function rewrapDek(envelope: Envelope, provider: MasterKeyProvider): Promise<Envelope>;

package/dist/secrets/rotation.js

@@ -0,0 +1,29 @@
+// KEK rotation: unwrap the DEK with the OLD kekVersion, re-wrap with the
+// CURRENT one. The ciphertext never changes — this is why envelope
+// encryption makes rotation affordable on large tables.
+// Re-wrap the DEK of a single envelope so it references the current KEK
+// version. No-op when the envelope is already current (caller-side this
+// means "filter WHERE kekVersion != currentVersion" before calling).
+export async function rewrapDek(envelope, provider) {
+    if (envelope.kekVersion === provider.currentVersion()) {
+        return envelope;
+    }
+    // Unwrap with the old KEK. Provider must still know the old version
+    // (keyring contains both until ops retires the old KEK).
+    const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion);
+    try {
+        const { encryptedDek, kekVersion } = await provider.wrapDek(dek);
+        return {
+            ciphertext: envelope.ciphertext,
+            iv: envelope.iv,
+            authTag: envelope.authTag,
+            encryptedDek,
+            kekVersion,
+        };
+    }
+    finally {
+        // Zero the unwrapped DEK — it was held in plaintext only long enough
+        // to wrap it again.
+        dek.fill(0);
+    }
+}

package/dist/secrets/stored-envelope.d.ts

@@ -0,0 +1,11 @@
+import type { Envelope } from "./types.js";
+export type StoredEnvelope = {
+    readonly ciphertext: string;
+    readonly iv: string;
+    readonly authTag: string;
+    readonly encryptedDek: string;
+    readonly kekVersion: number;
+};
+export declare function encodeStoredEnvelope(envelope: Envelope): StoredEnvelope;
+export declare function decodeStoredEnvelope(stored: StoredEnvelope): Envelope;
+export declare function isStoredEnvelope(value: unknown): value is StoredEnvelope;

package/dist/secrets/stored-envelope.js

@@ -0,0 +1,32 @@
+// Canonical at-rest form of an Envelope: every Buffer as base64, ready for
+// jsonb columns (secrets feature) or JSON-stringified TEXT columns
+// (EnvelopeCipher for config values / entity fields). One wire shape for
+// every envelope-encrypted store in the framework.
+export function encodeStoredEnvelope(envelope) {
+    return {
+        ciphertext: envelope.ciphertext.toString("base64"),
+        iv: envelope.iv.toString("base64"),
+        authTag: envelope.authTag.toString("base64"),
+        encryptedDek: envelope.encryptedDek.toString("base64"),
+        kekVersion: envelope.kekVersion,
+    };
+}
+export function decodeStoredEnvelope(stored) {
+    return {
+        ciphertext: Buffer.from(stored.ciphertext, "base64"),
+        iv: Buffer.from(stored.iv, "base64"),
+        authTag: Buffer.from(stored.authTag, "base64"),
+        encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
+        kekVersion: stored.kekVersion,
+    };
+}
+export function isStoredEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value; // @cast-boundary parse-boundary after typeof check
+    return (typeof v["ciphertext"] === "string" &&
+        typeof v["iv"] === "string" &&
+        typeof v["authTag"] === "string" &&
+        typeof v["encryptedDek"] === "string" &&
+        typeof v["kekVersion"] === "number");
+}

package/dist/secrets/types.d.ts

@@ -0,0 +1 @@
+export * from "@cosmicdrift/kumiko-types/secrets-types";

package/dist/seeding/entity-seed.d.ts

@@ -0,0 +1,19 @@
+import { type SeedIfExists } from "./types.js";
+export type EventStoreSeedExisting<TId extends string | number = string> = {
+    readonly id: TId;
+    readonly version: number;
+};
+export type RunEventStoreSeedOptions<TId extends string | number = string, TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>> = {
+    readonly existing: TExisting | null | undefined;
+    readonly ifExists?: SeedIfExists;
+    readonly create: () => Promise<{
+        id: TId;
+    }>;
+    readonly update: (existing: TExisting) => Promise<{
+        id: TId;
+    }>;
+};
+/** Shared create-or-skip/update path for event-store boot-seed helpers. */
+export declare function runEventStoreSeed<TId extends string | number = string, TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>>(opts: RunEventStoreSeedOptions<TId, TExisting>): Promise<{
+    id: TId;
+}>;

package/dist/seeding/entity-seed.js

@@ -0,0 +1,12 @@
+import { DEFAULT_SEED_IF_EXISTS } from "./types.js";
+/** Shared create-or-skip/update path for event-store boot-seed helpers. */
+export async function runEventStoreSeed(opts) {
+    const ifExists = opts.ifExists ?? DEFAULT_SEED_IF_EXISTS;
+    if (opts.existing != null) {
+        if (ifExists === "skip") {
+            return { id: opts.existing.id };
+        }
+        return opts.update(opts.existing);
+    }
+    return opts.create();
+}

package/dist/seeding/index.d.ts

@@ -0,0 +1,2 @@
+export { type EventStoreSeedExisting, type RunEventStoreSeedOptions, runEventStoreSeed, } from "./entity-seed.js";
+export { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types.js";

package/dist/seeding/index.js

@@ -0,0 +1,2 @@
+export { runEventStoreSeed, } from "./entity-seed.js";
+export { DEFAULT_SEED_IF_EXISTS } from "./types.js";

package/dist/seeding/types.d.ts

@@ -0,0 +1,7 @@
+/** Boot-seed semantics for event-sourced entity helpers.
+ *
+ *  - `skip` (default): row exists → return without write (no event).
+ *  - `update`: row exists → overwrite via executor.update (opt-in, e.g.
+ *    demo-fixtures where code is source-of-truth). */
+export type SeedIfExists = "skip" | "update";
+export declare const DEFAULT_SEED_IF_EXISTS: SeedIfExists;

package/dist/seeding/types.js

@@ -0,0 +1 @@
+export const DEFAULT_SEED_IF_EXISTS = "skip";

package/dist/stack/db.d.ts

@@ -0,0 +1,19 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-types/db-connection";
+declare function requireEnv(name: string): string;
+export type TestDb = {
+    db: DbConnection;
+    client: unknown;
+    dbName: string;
+    cleanup: () => Promise<void>;
+};
+export type CreateTestDbOptions = {
+    readonly baseUrl?: string;
+    readonly dbName?: string;
+    readonly persistent?: boolean;
+};
+/**
+ * Provider-agnostische Test-DB. createConnection liest DB_PROVIDER.
+ * Für Bun.SQL: DB_PROVIDER=bun setzen (experimentell — siehe db/bun-provider.ts).
+ */
+export declare function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb>;
+export { requireEnv };

package/dist/stack/db.js

@@ -0,0 +1,61 @@
+// Test-DB Factory: CREATE DATABASE → connect → createEventsTable.
+// Provider-agnostic via createConnection (DB_PROVIDER env).
+// postgres-js = default. DB_PROVIDER=bun = Bun.SQL (experimentell).
+import { createConnection } from "../db/api.js";
+import { createDatabase, databaseExists, dropDatabaseIfExists } from "../db/queries/test-stack.js";
+import { ensureTemporalPolyfill } from "../time/polyfill.js";
+import { generateId } from "../utils/index.js";
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required env var: ${name}. Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".`);
+    }
+    return value;
+}
+/**
+ * Provider-agnostische Test-DB. createConnection liest DB_PROVIDER.
+ * Für Bun.SQL: DB_PROVIDER=bun setzen (experimentell — siehe db/bun-provider.ts).
+ */
+export async function createTestDb(arg) {
+    await ensureTemporalPolyfill();
+    const opts = typeof arg === "string" ? { baseUrl: arg } : (arg ?? {});
+    const url = opts.baseUrl ?? requireEnv("TEST_DATABASE_URL");
+    const dbName = opts.dbName ?? `kumiko_test_${generateId().slice(-8)}`;
+    const adminUrl = url.replace(/\/[^/]+$/, "/postgres");
+    const admin = await createConnection(adminUrl, { maxConnections: 1 });
+    try {
+        if (opts.persistent) {
+            if (!(await databaseExists(admin.db, dbName))) {
+                await createDatabase(admin.db, dbName);
+            }
+        }
+        else {
+            await createDatabase(admin.db, dbName);
+        }
+    }
+    finally {
+        await admin.close();
+    }
+    const testUrl = url.replace(/\/[^/]+$/, `/${dbName}`);
+    const conn = await createConnection(testUrl);
+    const { createEventsTable } = await import("../event-store/index.js");
+    await createEventsTable(conn.db);
+    return {
+        db: conn.db,
+        client: conn.client,
+        dbName,
+        cleanup: async () => {
+            await conn.close();
+            if (!opts.persistent) {
+                const admin2 = await createConnection(adminUrl, { maxConnections: 1 });
+                try {
+                    await dropDatabaseIfExists(admin2.db, dbName);
+                }
+                finally {
+                    await admin2.close();
+                }
+            }
+        },
+    };
+}
+export { requireEnv };

package/dist/stack/drain-event-consumers.d.ts

@@ -0,0 +1,4 @@
+import type { TestStack } from "./test-stack.js";
+export declare function drainEventConsumers(stack: Pick<TestStack, "db" | "eventDispatcher">, consumerNames: readonly [string, ...string[]], options?: {
+    readonly maxPasses?: number;
+}): Promise<void>;

package/dist/stack/drain-event-consumers.js

@@ -0,0 +1,48 @@
+import { getEventsHighWaterMark } from "../event-store/index.js";
+import { getConsumerState } from "../pipeline/index.js";
+const DEFAULT_MAX_PASSES = 25;
+// Drives eventDispatcher.runOnce() until every named consumer has caught up
+// to the events high-water mark captured at call time. No "no progress ⇒
+// throw" shortcut: a pass can legitimately advance zero cursors even though
+// work remains — runOnce's FOR UPDATE SKIP LOCKED lets a concurrent pass
+// (the test stack's own 50ms poll timer) hold a consumer's row, and a
+// consumer coming off a thrown-pass backoff sits idle until its retryAtMs
+// elapses. A bounded pass budget tolerates both without pretending to detect
+// "stuck" from a single empty pass. The target is a snapshot: events a
+// consumer's own handler writes afterward (cascades) are not waited on.
+export async function drainEventConsumers(stack, consumerNames, options) {
+    const { db, eventDispatcher } = stack;
+    if (!eventDispatcher) {
+        throw new Error("drainEventConsumers: stack.eventDispatcher is undefined — no system consumer or " +
+            "multiStreamProjection is wired for this stack.");
+    }
+    const maxPasses = options?.maxPasses ?? DEFAULT_MAX_PASSES;
+    const target = await getEventsHighWaterMark(db);
+    for (let pass = 0; pass < maxPasses; pass++) {
+        await eventDispatcher.runOnce();
+        const states = await loadConsumerStates(db, consumerNames);
+        // skip: every named consumer has already caught up to the target snapshot — the
+        // remaining budgeted passes are unnecessary, not a swallowed error.
+        if (states.every((state) => state.lastProcessedEventId >= target))
+            return;
+        if (pass === maxPasses - 1) {
+            throw budgetExhaustedError(maxPasses, target, states);
+        }
+    }
+}
+async function loadConsumerStates(db, consumerNames) {
+    return Promise.all(consumerNames.map(async (name) => {
+        const state = await getConsumerState(db, name);
+        if (!state) {
+            throw new Error(`drainEventConsumers: consumer "${name}" not registered or per-instance`);
+        }
+        return state;
+    }));
+}
+function budgetExhaustedError(maxPasses, target, states) {
+    const unfinished = states.filter((state) => state.lastProcessedEventId < target);
+    const lines = unfinished.map((state) => `  ${state.name}: lastProcessedEventId=${state.lastProcessedEventId} target=${target} ` +
+        `status=${state.status} attempts=${state.attempts} lastError=${state.lastError ?? "null"}`);
+    return new Error(`drainEventConsumers: budget of ${maxPasses} passes exhausted, consumers still behind target:\n` +
+        lines.join("\n"));
+}

package/dist/stack/drain-jobs.d.ts

@@ -0,0 +1,20 @@
+import type { DbConnection } from "../db/index.js";
+import type { JobRunner } from "../jobs/index.js";
+import { type EventDispatcher } from "../pipeline/index.js";
+export type JobFailureTracker = {
+    readonly onJobComplete: (jobName: string, jobId: string) => void;
+    readonly onJobFailed: (jobName: string, jobId: string, error: string) => void;
+    waitForActivity(): Promise<void>;
+    readonly failures: ReadonlyMap<string, {
+        readonly jobName: string;
+        readonly error: string;
+    }>;
+    clear(): void;
+};
+export declare function createJobFailureTracker(): JobFailureTracker;
+export type DrainJobsStack = {
+    readonly db: DbConnection;
+    readonly eventDispatcher?: EventDispatcher;
+    readonly jobRunner?: JobRunner;
+};
+export declare function drainJobs(stack: DrainJobsStack, tracker: JobFailureTracker): Promise<void>;

package/dist/stack/drain-jobs.js

@@ -0,0 +1,99 @@
+import { getEventsHighWaterMark } from "../event-store/index.js";
+import { getConsumerState } from "../pipeline/index.js";
+// Gap between idle-checks while waiting for a job hook to fire. Short enough
+// that a test never feels it, long enough that consecutive idle passes don't
+// hammer Postgres/Redis with pointless polling between hook-driven wakeups.
+const DRAIN_IDLE_POLL_MS = 25;
+// Two consecutive idle passes (not one) before declaring the stack drained —
+// a single "pending===0 and consumers caught up" pass can be a race: a job
+// hook fires and enqueues a follow-up between the countPendingJobs() read
+// and the consumer check of the SAME pass. A DRAIN_IDLE_POLL_MS wait sits
+// between every pass, including the first and second idle one, so an
+// enqueue that lands just after the first idle read still gets picked up
+// by the second pass instead of racing straight past it.
+const REQUIRED_IDLE_PASSES = 2;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function createJobFailureTracker() {
+    const failures = new Map();
+    let wake;
+    let armed;
+    function fire() {
+        wake?.();
+        armed = undefined;
+        wake = undefined;
+    }
+    return {
+        onJobComplete(_jobName, jobId) {
+            // A retry that eventually succeeds must not leave a stale failure
+            // behind from its earlier attempt(s).
+            failures.delete(jobId);
+            fire();
+        },
+        onJobFailed(jobName, jobId, error) {
+            failures.set(jobId, { jobName, error });
+            fire();
+        },
+        waitForActivity() {
+            armed ??= new Promise((resolve) => {
+                wake = resolve;
+            });
+            return armed;
+        },
+        failures,
+        clear() {
+            failures.clear();
+        },
+    };
+}
+async function sharedConsumersCaughtUp(db, consumerNames) {
+    // skip: no shared consumers wired — nothing to catch up on.
+    if (consumerNames.length === 0)
+        return true;
+    const target = await getEventsHighWaterMark(db);
+    let allCaughtUp = true;
+    for (const name of consumerNames) {
+        const state = await getConsumerState(db, name);
+        if (!state) {
+            throw new Error(`drainJobs: consumer "${name}" not registered or per-instance`);
+        }
+        if (state.status === "dead") {
+            throw new Error(`drainJobs: consumer "${state.name}" is dead — lastError: ${state.lastError ?? "unknown"}`);
+        }
+        if (state.lastProcessedEventId < target)
+            allCaughtUp = false;
+    }
+    return allCaughtUp;
+}
+export async function drainJobs(stack, tracker) {
+    const { db, eventDispatcher, jobRunner } = stack;
+    if (!jobRunner) {
+        throw new Error("drainJobs: stack.jobRunner is undefined — pass `jobs: {...}` to setupTestStack and " +
+            "register at least one r.job(...) so a runner is built.");
+    }
+    const sharedConsumerNames = (eventDispatcher?.consumers ?? [])
+        .filter((consumer) => (consumer.delivery ?? "shared") === "shared")
+        .map((consumer) => consumer.name);
+    try {
+        let consecutiveIdlePasses = 0;
+        while (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
+            await eventDispatcher?.runOnce();
+            const pending = await jobRunner.countPendingJobs();
+            const caughtUp = await sharedConsumersCaughtUp(db, sharedConsumerNames);
+            consecutiveIdlePasses = pending === 0 && caughtUp ? consecutiveIdlePasses + 1 : 0;
+            if (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
+                await Promise.race([tracker.waitForActivity(), sleep(DRAIN_IDLE_POLL_MS)]);
+            }
+        }
+        if (tracker.failures.size > 0) {
+            const details = [...tracker.failures.values()]
+                .map((failure) => `${failure.jobName}: ${failure.error}`)
+                .join("; ");
+            throw new Error(`drainJobs: job(s) failed: ${details}`);
+        }
+    }
+    finally {
+        tracker.clear();
+    }
+}

package/dist/stack/event-collector.d.ts

@@ -0,0 +1,9 @@
+import type { SseEvent } from "../api/sse-broker.js";
+import type { SaveContext } from "../engine/types/index.js";
+export type EventCollector = {
+    readonly sse: SseEvent[];
+    readonly postSave: SaveContext[];
+    /** Clears all collected events — call in beforeEach for per-test isolation */
+    reset(): void;
+};
+export declare function createEventCollector(): EventCollector;

package/dist/stack/event-collector.js

@@ -0,0 +1,12 @@
+export function createEventCollector() {
+    const sse = [];
+    const postSave = [];
+    return {
+        sse,
+        postSave,
+        reset() {
+            sse.length = 0;
+            postSave.length = 0;
+        },
+    };
+}

package/dist/stack/index.d.ts

@@ -0,0 +1,9 @@
+export { type CreateTestDbOptions, createTestDb, type TestDb, } from "./db.js";
+export { drainEventConsumers } from "./drain-event-consumers.js";
+export { createEventCollector, type EventCollector } from "./event-collector.js";
+export { pushEntityProjectionTables } from "./push-entity-projection-tables.js";
+export { createTestRedis, type TestRedis } from "./redis.js";
+export { createRequestHelper, type RequestHelper } from "./request-helper.js";
+export { resetEventStore, unsafeCreateEntityTable, unsafeEnsureEntityTable, unsafePushTables, } from "./table-helpers.js";
+export { setupTestStack, type TestStack, type TestStackOptions } from "./test-stack.js";
+export { createTestUser, TestUsers, testTenantId, testUserId, } from "./test-users.js";

package/dist/stack/index.js

@@ -0,0 +1,19 @@
+// Runtime-safe Stack-Builder. Was hier liegt, wird vom dev-server zum Hochfahren
+// einer kompletten Kumiko-Instanz genutzt — DB, Redis, Hono-App, Dispatcher,
+// SSE-Broker. Die Files heißen historisch `test*` (createTestDb,
+// setupTestStack, TestUsers, …), bedienen aber heute Dev- UND Test-Code: das
+// ist genau derselbe Hochfahr-Pfad, nur einmal mit ephemeral-DB (test) und
+// einmal mit persistent-DB (dev).
+//
+// Wichtig: dieses Modul darf KEINE vitest-Imports enthalten und keine
+// Vitest-only Helper transitiv ziehen — sonst crasht jedes Tooling, das den
+// dev-server unter Node lädt (drizzle-kit, build-scripts).
+export { createTestDb, } from "./db.js";
+export { drainEventConsumers } from "./drain-event-consumers.js";
+export { createEventCollector } from "./event-collector.js";
+export { pushEntityProjectionTables } from "./push-entity-projection-tables.js";
+export { createTestRedis } from "./redis.js";
+export { createRequestHelper } from "./request-helper.js";
+export { resetEventStore, unsafeCreateEntityTable, unsafeEnsureEntityTable, unsafePushTables, } from "./table-helpers.js";
+export { setupTestStack } from "./test-stack.js";
+export { createTestUser, TestUsers, testTenantId, testUserId, } from "./test-users.js";

package/dist/stack/push-entity-projection-tables.d.ts

@@ -0,0 +1,24 @@
+import type { DbConnection } from "../db/connection.js";
+import type { Registry } from "../engine/types/index.js";
+type DbHolder = {
+    readonly db: DbConnection;
+};
+/**
+ * Push all implicit-projection tables — one per `r.entity()` — that the
+ * registry knows about. setupTestStack already handles explicit
+ * projections, MSPs, and `r.storeTable()` declarations in its own loop;
+ * implicit projections are the missing piece for a fresh boot.
+ *
+ * Idempotent via `tableExists` so a persistent dev DB
+ * (`KUMIKO_DEV_DB_NAME`) reuses existing tables on reboot. One batched
+ * push at the end so drizzle-kit's `generateMigration` runs once over
+ * the whole missing set.
+ *
+ * Lives next to `setupTestStack` because both are stack-bootstrap
+ * helpers that legitimately speak the `unsafe*`-DDL layer; the
+ * Table-DDL Guard's stack/** allowlist is the single shared exemption
+ * site. Apps still declare data via `r.entity()` / `r.storeTable()` and
+ * never call this directly.
+ */
+export declare function pushEntityProjectionTables(stack: DbHolder, registry: Registry): Promise<void>;
+export {};