@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/stack/push-entity-projection-tables.js

@@ -0,0 +1,73 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { columnNamesOf, tableExists } from "../db/schema-inspection.js";
+import { addMissingColumns, tableToMeta, unsafePushTables } from "./table-helpers.js";
+// biome-ignore lint/suspicious/noConsole: stack-internal status logging
+const logInfo = (msg) => console.log(msg);
+/**
+ * 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 async function pushEntityProjectionTables(stack, registry) {
+    const seen = new Set();
+    const missing = {};
+    for (const [projName, proj] of registry.getAllProjections()) {
+        if (!proj.isImplicit)
+            continue;
+        if (seen.has(proj.table))
+            continue;
+        seen.add(proj.table);
+        const tableRec = proj.table;
+        const physical = tableRec[KUMIKO_NAME_SYMBOL];
+        if (!(await tableExists(stack.db, `public.${physical}`))) {
+            missing[projName] = proj.table;
+            continue;
+        }
+        await syncExistingProjectionTable(stack, physical, proj.table);
+    }
+    if (Object.keys(missing).length > 0) {
+        await unsafePushTables(stack.db, missing);
+    }
+}
+function isUnsafeToAutoAdd(col) {
+    return col.notNull && !col.primaryKey && col.defaultSql === undefined;
+}
+// Backfills columns a persistent dev DB predates; a required column with no
+// default can't be added safely on a table that may hold rows, so that
+// stays a boot error instead.
+async function syncExistingProjectionTable(stack, physical, table) {
+    const meta = tableToMeta(table);
+    const liveColumns = await columnNamesOf(stack.db, physical);
+    const missingColumns = meta.columns.filter((c) => !liveColumns.has(c.name));
+    if (missingColumns.length === 0) {
+        logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
+        // skip: live table already has every declared column
+        return;
+    }
+    const unsafeColumns = missingColumns.filter(isUnsafeToAutoAdd);
+    if (unsafeColumns.length > 0) {
+        const devDbName = process.env["KUMIKO_DEV_DB_NAME"] ?? "<KUMIKO_DEV_DB_NAME>";
+        throw new Error(`[kumiko-stack] table "${physical}" is missing required column(s) ` +
+            `${unsafeColumns.map((c) => `"${c.name}"`).join(", ")} with no default. ` +
+            "Auto-sync only backfills nullable columns or columns with a default on an " +
+            "existing dev DB — a required column with no default can't be added safely " +
+            `once the table may hold rows. Drop the persistent dev database "${devDbName}" ` +
+            `(e.g. \`dropdb ${devDbName}\`, adjusted for your local Postgres host/port/user) ` +
+            "so the next boot recreates it from scratch.");
+    }
+    logInfo(`[kumiko-stack] table ${physical} is missing column(s) ` +
+        `${missingColumns.map((c) => `"${c.name}"`).join(", ")} — adding`);
+    await addMissingColumns(stack.db, physical, missingColumns);
+}

package/dist/stack/redis.d.ts

@@ -0,0 +1,11 @@
+export type TestRedis = {
+    redis: import("ioredis").Redis;
+    redisUrl: string;
+    /** The per-test `keyPrefix` on `redis`, e.g. `kt:1a2b3c4d:`. */
+    keyPrefix: string;
+    /** Delete every key this test created (prefix-scoped). Replaces the old
+     *  `redis.flushdb()` — that wiped other parallel tests' BullMQ state. */
+    flushNamespace: () => Promise<void>;
+    cleanup: () => Promise<void>;
+};
+export declare function createTestRedis(): Promise<TestRedis>;

package/dist/stack/redis.js

@@ -0,0 +1,38 @@
+import { generateId } from "../utils/index.js";
+import { requireEnv } from "./db.js";
+export async function createTestRedis() {
+    const Redis = (await import("ioredis")).Redis;
+    const redisUrl = requireEnv("REDIS_URL");
+    // Every test gets a per-file key prefix on a shared DB (no DB-pool-of-15
+    // round-robin). Collisions at birthday-paradox rates are gone — the
+    // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
+    const prefix = `kt:${generateId().slice(-8)}:`;
+    const redis = new Redis(redisUrl, { keyPrefix: prefix });
+    async function flushNamespace() {
+        // Open a prefix-less client for the scan — ioredis' keyPrefix is applied
+        // per-command but SCAN's returned keys are full names, so managing the
+        // del set with the prefix already on the connection is error-prone.
+        const raw = new Redis(redisUrl);
+        try {
+            const stream = raw.scanStream({ match: `${prefix}*`, count: 500 });
+            const keys = [];
+            for await (const batch of stream)
+                keys.push(...batch);
+            if (keys.length > 0)
+                await raw.del(...keys);
+        }
+        finally {
+            raw.disconnect();
+        }
+    }
+    return {
+        redis,
+        redisUrl,
+        keyPrefix: prefix,
+        flushNamespace,
+        cleanup: async () => {
+            await flushNamespace();
+            redis.disconnect();
+        },
+    };
+}

package/dist/stack/request-helper.d.ts

@@ -0,0 +1,35 @@
+import type { Hono } from "hono";
+import type { SessionCreator } from "../api/auth-routes.js";
+import type { JwtHelper } from "../api/jwt.js";
+import type { SessionUser } from "../engine/types/index.js";
+export type BatchCommand = {
+    type: string;
+    payload: unknown;
+};
+export type RequestHelper = {
+    write: (type: string, payload: unknown, user: SessionUser, requestId?: string) => Promise<Response>;
+    query: (type: string, payload: unknown, user: SessionUser) => Promise<Response>;
+    command: (type: string, payload: unknown, user: SessionUser) => Promise<Response>;
+    batch: (commands: readonly BatchCommand[], user: SessionUser, requestId?: string) => Promise<Response>;
+    raw: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<Response>;
+    /** write + json + assert isSuccess — returns data directly */
+    writeOk: <T = Record<string, unknown>>(type: string, payload: unknown, user: SessionUser, requestId?: string) => Promise<T>;
+    /** write + json + assert isSuccess === false — returns the structured
+     *  WriteErrorInfo with `httpStatus` filled in from the HTTP response. */
+    writeErr: (type: string, payload: unknown, user: SessionUser) => Promise<import("../errors/index.js").WriteErrorInfo>;
+    /** query + json — returns data directly */
+    queryOk: <T = unknown>(type: string, payload: unknown, user: SessionUser) => Promise<T>;
+    /** query + json + assert the response is an error — returns the structured
+     *  WriteErrorInfo with `httpStatus` filled in from the HTTP response. */
+    queryErr: (type: string, payload: unknown, user: SessionUser) => Promise<import("../errors/index.js").WriteErrorInfo>;
+    /** write + additional HTTP headers (e.g. X-Correlation-ID). Returns the
+     *  raw Response so callers can assert on status + headers + body as needed. */
+    writeWithHeaders: (type: string, payload: unknown, user: SessionUser, extraHeaders: Record<string, string>) => Promise<Response>;
+    /** query + additional HTTP headers (e.g. X-Forwarded-For). Returns the raw
+     *  Response so callers can assert on status + headers + body as needed. */
+    queryWithHeaders: (type: string, payload: unknown, user: SessionUser, extraHeaders: Record<string, string>) => Promise<Response>;
+};
+export type RequestHelperOptions = {
+    readonly sessionCreator?: SessionCreator;
+};
+export declare function createRequestHelper(app: Hono, jwt: JwtHelper, options?: RequestHelperOptions): RequestHelper;

package/dist/stack/request-helper.js

@@ -0,0 +1,144 @@
+function formatFailure(kind, type, body) {
+    const parsed = body;
+    const code = (typeof parsed.error === "object" ? parsed.error?.code : undefined) ??
+        (typeof parsed.error === "string" ? parsed.error : "unknown");
+    const details = typeof parsed.error === "object" && parsed.error?.details !== undefined
+        ? parsed.error.details
+        : undefined;
+    const causeMessage = details && typeof details === "object" && "causeMessage" in details
+        ? String(details.causeMessage ?? "")
+        : "";
+    const causeName = details && typeof details === "object" && "causeName" in details
+        ? String(details.causeName ?? "")
+        : "";
+    if (code === "internal_error" && (causeMessage || causeName)) {
+        return `Expected ${kind} "${type}" to succeed but got error: ${code} (${causeName}: ${causeMessage})`;
+    }
+    if (details !== undefined) {
+        return `Expected ${kind} "${type}" to succeed but got error: ${code} — ${JSON.stringify(details)}`;
+    }
+    return `Expected ${kind} "${type}" to succeed but got error: ${code}`;
+}
+export function createRequestHelper(app, jwt, options = {}) {
+    // sid per (user.id, tenantId), not one mint per authHeader() call:
+    // sessionCreator opens a live session row, so an unmemoized call mints a
+    // fresh one on every request a test makes for the same user — tests
+    // asserting on session counts / massRevoker / revokeAllOthers behavior
+    // then see extra live sids that have nothing to do with what they're
+    // testing. Keyed on tenantId too — the same user.id can hold sessions in
+    // more than one tenant, and sessionCreator writes the row scoped to
+    // `user.tenantId` (session-callbacks.ts), so a user.id-only key would
+    // hand a cross-tenant test its wrong tenant's sid.
+    // Cache the Promise (not the settled sid) so two concurrent authHeader
+    // calls for the same key share one mint instead of racing on a miss.
+    const sidByUserKey = new Map();
+    async function authHeader(user) {
+        let forJwt = user;
+        if (options.sessionCreator && !user.sid) {
+            const key = `${user.id}:${user.tenantId}`;
+            let sidPromise = sidByUserKey.get(key);
+            if (sidPromise === undefined) {
+                sidPromise = options.sessionCreator(user, { ip: "test", userAgent: "request-helper" });
+                sidByUserKey.set(key, sidPromise);
+            }
+            const sid = await sidPromise;
+            forJwt = { ...user, sid };
+        }
+        const token = await jwt.sign(forJwt);
+        return { Authorization: `Bearer ${token}` };
+    }
+    async function req(method, path, body, headers) {
+        const init = {
+            method,
+            headers: { "Content-Type": "application/json", ...headers },
+        };
+        if (body)
+            init.body = JSON.stringify(body);
+        return app.request(path, init);
+    }
+    async function writeRaw(type, payload, user, requestId) {
+        const headers = await authHeader(user);
+        return req("POST", "/api/write", { type, payload, requestId }, headers);
+    }
+    async function queryRaw(type, payload, user) {
+        const headers = await authHeader(user);
+        return req("POST", "/api/query", { type, payload }, headers);
+    }
+    return {
+        write: writeRaw,
+        query: queryRaw,
+        async command(type, payload, user) {
+            const headers = await authHeader(user);
+            return req("POST", "/api/command", { type, payload }, headers);
+        },
+        async batch(commands, user, requestId) {
+            const headers = await authHeader(user);
+            return req("POST", "/api/batch", { commands, requestId }, headers);
+        },
+        raw: req,
+        async writeOk(type, payload, user, requestId) {
+            const res = await writeRaw(type, payload, user, requestId);
+            // wire-body shape direkt nach JSON.parse — Caller-Code prüft danach
+            // selber ob isSuccess/error/data tatsächlich da sind.
+            const rawBody = await res.json();
+            const body = rawBody;
+            // Success path still has { isSuccess: true, data }. Error responses now
+            // follow the error-contract shape { error: { code, i18nKey, ... } } with
+            // a 4xx/5xx status — no isSuccess flag. Detect either.
+            if (body.isSuccess !== true) {
+                throw new Error(formatFailure("write", type, body));
+            }
+            return body.data; // @cast-boundary engine-bridge
+        },
+        async writeErr(type, payload, user) {
+            const res = await writeRaw(type, payload, user);
+            const rawErrorBody = await res.json();
+            const body = rawErrorBody;
+            if (body.isSuccess === true) {
+                throw new Error(`Expected write "${type}" to fail but it succeeded`);
+            }
+            const wire = body.error;
+            if (!wire || typeof wire !== "object" || typeof wire.code !== "string") {
+                throw new Error(`Expected error response for "${type}" but got unexpected shape: ${JSON.stringify(body)}`);
+            }
+            // The wire body doesn't carry httpStatus (it would be redundant with
+            // the HTTP response status). Fill it in from res.status so callers can
+            // assert against either code OR status without a second request round.
+            return { ...wire, httpStatus: res.status };
+        },
+        async queryOk(type, payload, user) {
+            const res = await queryRaw(type, payload, user);
+            const rawBody = await res.json();
+            const body = rawBody;
+            // res.ok mirrors writeOk's isSuccess assertion — belt-and-suspenders
+            // in case a future non-dispatcher rejection skips the error-contract shape.
+            if (!res.ok || body.error !== undefined) {
+                throw new Error(`${formatFailure("query", type, body)} [HTTP ${res.status}]`);
+            }
+            return body.data; // @cast-boundary engine-bridge
+        },
+        async queryErr(type, payload, user) {
+            const res = await queryRaw(type, payload, user);
+            const rawErrorBody = await res.json();
+            const body = rawErrorBody;
+            if (res.ok) {
+                throw new Error(`Expected query "${type}" to fail but it succeeded`);
+            }
+            const wire = body.error;
+            if (!wire || typeof wire !== "object" || typeof wire.code !== "string") {
+                throw new Error(`Expected error response for "${type}" but got unexpected shape: ${JSON.stringify(body)}`);
+            }
+            // Same rationale as writeErr: the wire body has no httpStatus (it would
+            // be redundant with the HTTP response status), so fill it in here.
+            return { ...wire, httpStatus: res.status };
+        },
+        async writeWithHeaders(type, payload, user, extraHeaders) {
+            const authHeaders = await authHeader(user);
+            return req("POST", "/api/write", { type, payload }, { ...authHeaders, ...extraHeaders });
+        },
+        async queryWithHeaders(type, payload, user, extraHeaders) {
+            const authHeaders = await authHeader(user);
+            return req("POST", "/api/query", { type, payload }, { ...authHeaders, ...extraHeaders });
+        },
+    };
+}

package/dist/stack/table-helpers.d.ts

@@ -0,0 +1,32 @@
+import type { DbConnection } from "../db/connection.js";
+import type { ColumnMeta, EntityTableMeta } from "../db/entity-table-meta.js";
+import type { EventDispatcher } from "../pipeline/index.js";
+/**
+ * Bypass: creates an entity-table directly without going through the
+ * full registry. Reserved for framework-internal meta-tables and
+ * test setup — apps declare data via `r.entity(...)`.
+ */
+export declare function unsafeCreateEntityTable(db: DbConnection, entity: import("../engine/types/index.js").EntityDefinition, entityName?: string): Promise<void>;
+export declare function unsafeEnsureEntityTable(db: DbConnection, entity: import("../engine/types/index.js").EntityDefinition, entityName?: string): Promise<boolean>;
+export declare function tableToMeta(table: unknown): EntityTableMeta;
+/** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
+export declare function addMissingColumns(db: DbConnection, tableName: string, columns: readonly ColumnMeta[]): Promise<void>;
+/**
+ * Bypass: pushes table definitions to the database directly. Produces
+ * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
+ * and executes them via db/queries/test-stack. Idempotent re-runs are safe.
+ *
+ * Reserved for framework-internal meta-tables + test setup. App-defined
+ * entities go through `kumiko schema apply` (committed SQL files).
+ */
+export declare function unsafePushTables(db: DbConnection, tables: Record<string, unknown>, prevTables?: Record<string, unknown>): Promise<void>;
+/**
+ * Wipes event store + framework-state + the given feature read-models in
+ * one TRUNCATE, then re-registers the event-consumer state rows. Used in
+ * test beforeEach-hooks to return the stack to a clean slate without
+ * rebuilding it.
+ */
+export declare function resetEventStore(stack: {
+    db: unknown;
+    eventDispatcher?: EventDispatcher;
+}, extraTables?: readonly (unknown | string)[]): Promise<void>;

package/dist/stack/table-helpers.js

@@ -0,0 +1,138 @@
+import { KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { pgTypeToSqlType } from "../db/dialect.js";
+import { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement, } from "../db/queries/ddl.js";
+import { truncateTablesRestartIdentity } from "../db/queries/test-stack.js";
+import { renderTableDdl } from "../db/render-ddl.js";
+import { tableExists } from "../db/schema-inspection.js";
+import { buildEntityTable, toTableName } from "../db/table-builder.js";
+function tableNameOf(table) {
+    if (typeof table !== "object" || table === null) {
+        throw new Error("table-helpers: table is not a SchemaTable object");
+    }
+    const rec = table;
+    if (typeof rec[KUMIKO_NAME_SYMBOL] === "string")
+        return rec[KUMIKO_NAME_SYMBOL];
+    if (typeof rec.tableName === "string") {
+        return rec.tableName;
+    }
+    throw new Error("table-helpers: table has no name");
+}
+/**
+ * Bypass: creates an entity-table directly without going through the
+ * full registry. Reserved for framework-internal meta-tables and
+ * test setup — apps declare data via `r.entity(...)`.
+ */
+export async function unsafeCreateEntityTable(db, entity, entityName) {
+    const table = buildEntityTable(entityName ?? "entity", entity);
+    await unsafePushTables(db, { [entityName ?? "entity"]: table });
+}
+export async function unsafeEnsureEntityTable(db, entity, entityName) {
+    const resolvedName = entity.table ?? toTableName(entityName ?? "entity");
+    if (await tableExists(db, `public.${resolvedName}`))
+        return false;
+    await unsafeCreateEntityTable(db, entity, entityName);
+    return true;
+}
+// Tables produced by the native dialect already carry EntityTableMeta-shape
+// (source/columns/indexes). renderTableDdl converts that to CREATE TABLE +
+// CREATE INDEX statements executed via db/queries/test-stack.
+function isMetaShape(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.tableName === "string" &&
+        Array.isArray(v.columns) &&
+        Array.isArray(v.indexes) &&
+        (v.source === "managed" || v.source === "unmanaged"));
+}
+export function tableToMeta(table) {
+    // table() spreads column handles as enumerable props, so a field named
+    // `columns`/`tableName`/`source`/… shadows the matching meta key — read the
+    // canonical meta from the unshadowable symbol when present.
+    if (table !== null && typeof table === "object") {
+        const fromSymbol = table[KUMIKO_META_SYMBOL];
+        if (isMetaShape(fromSymbol))
+            return fromSymbol;
+    }
+    if (isMetaShape(table))
+        return table;
+    throw new Error("unsafePushTables: argument is not a SchemaTable / EntityTableMeta");
+}
+/** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
+export async function addMissingColumns(db, tableName, columns) {
+    for (const col of columns) {
+        const type = renderColumnType(col);
+        const notNull = col.notNull && !col.primaryKey ? " NOT NULL" : "";
+        const defaultClause = col.defaultSql !== undefined ? ` DEFAULT ${col.defaultSql}` : "";
+        await alterTableAddColumn(db, tableName, col.name, type, defaultClause, notNull);
+    }
+}
+/**
+ * Bypass: pushes table definitions to the database directly. Produces
+ * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
+ * and executes them via db/queries/test-stack. Idempotent re-runs are safe.
+ *
+ * Reserved for framework-internal meta-tables + test setup. App-defined
+ * entities go through `kumiko schema apply` (committed SQL files).
+ */
+export async function unsafePushTables(db, tables, prevTables) {
+    const prevMetas = new Map();
+    if (prevTables) {
+        for (const [key, table] of Object.entries(prevTables)) {
+            const meta = tableToMeta(table);
+            prevMetas.set(key, meta);
+        }
+    }
+    for (const [key, table] of Object.entries(tables)) {
+        const meta = tableToMeta(table);
+        const prev = prevMetas.get(key);
+        if (prev) {
+            const prevCols = new Set(prev.columns.map((c) => c.name));
+            const newCols = meta.columns.filter((c) => !prevCols.has(c.name));
+            await addMissingColumns(db, meta.tableName, newCols);
+            const prevIdxNames = new Set(prev.indexes.map((i) => i.name));
+            for (const idx of meta.indexes) {
+                if (!prevIdxNames.has(idx.name)) {
+                    const kind = idx.unique ? "UNIQUE INDEX" : "INDEX";
+                    const colList = idx.columns.map((c) => `"${c}"`).join(", ");
+                    await createIndexIfNotExists(db, kind, idx.name, meta.tableName, colList, idx.whereSql);
+                }
+            }
+        }
+        else {
+            const statements = renderTableDdl(meta);
+            for (const stmt of statements) {
+                await executeDdlStatement(db, stmt);
+            }
+        }
+    }
+}
+// @wrapper-known semantic-alias
+function renderColumnType(col) {
+    return pgTypeToSqlType(col.pgType);
+}
+/**
+ * Wipes event store + framework-state + the given feature read-models in
+ * one TRUNCATE, then re-registers the event-consumer state rows. Used in
+ * test beforeEach-hooks to return the stack to a clean slate without
+ * rebuilding it.
+ */
+export async function resetEventStore(stack, extraTables = []) {
+    // A pass the dispatcher's own timer/LISTEN already started (from a
+    // preceding test) may still be writing into the tables truncated below —
+    // drain it first so the TRUNCATE never races a write it didn't cause.
+    if (stack.eventDispatcher) {
+        await stack.eventDispatcher.drain();
+    }
+    const frameworkTables = [
+        "kumiko_events",
+        "kumiko_event_consumers",
+        "kumiko_archived_streams",
+        "kumiko_snapshots",
+        "kumiko_projections",
+    ];
+    const extraNames = extraTables.map((t) => (typeof t === "string" ? t : tableNameOf(t)));
+    await truncateTablesRestartIdentity(stack.db, [...frameworkTables, ...extraNames]);
+    if (stack.eventDispatcher) {
+        await stack.eventDispatcher.ensureRegistered();
+    }
+}

package/dist/stack/test-stack.d.ts

@@ -0,0 +1,161 @@
+import type { Hono } from "hono";
+import type { AuthRoutesConfig } from "../api/auth-routes.js";
+import type { JwtHelper } from "../api/jwt.js";
+import { type SseBroker } from "../api/sse-broker.js";
+import type { AppContext, FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types/index.js";
+import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
+import type { Lifecycle } from "../lifecycle/index.js";
+import { type ObservabilityProvider } from "../observability/index.js";
+import type { Dispatcher, EventDispatcher } from "../pipeline/index.js";
+import type { SearchAdapter } from "../search/types.js";
+import { type EventCollector } from "./event-collector.js";
+import { type TestRedis } from "./redis.js";
+import { type RequestHelper } from "./request-helper.js";
+export type TestStack = {
+    app: Hono;
+    jwt: JwtHelper;
+    registry: Registry;
+    db: import("../db/index.js").DbConnection;
+    redis: TestRedis;
+    search: SearchAdapter;
+    events: EventCollector;
+    http: RequestHelper;
+    observability: ObservabilityProvider;
+    sseBroker: SseBroker;
+    dispatcher: Dispatcher;
+    context: AppContext;
+    eventDispatcher?: EventDispatcher;
+    lifecycle?: Lifecycle;
+    jobRunner?: JobRunner;
+    drainJobs: () => Promise<void>;
+    cleanup: () => Promise<void>;
+};
+export type TestStackOptions = {
+    features: readonly FeatureDefinition[];
+    /** System hooks to wire up. Default: all (sse, search) */
+    systemHooks?: ("sse" | "search")[];
+    /** Search config per tenant — defaults to tenant 1 with all text fields */
+    searchConfig?: {
+        tenantId: TenantId;
+        searchableFields: string[];
+        rankingFields: string[];
+    };
+    jwtSecret?: string;
+    /** Extra fields merged into the AppContext (e.g. _notifyFactory, configResolver).
+     *  Can be a function receiving (registry, db, sseBroker) for late binding. */
+    /** Boot default locale (BCP-47) merged into AppContext before extraContext. */
+    defaultLocale?: string;
+    extraContext?: Record<string, unknown> | ((deps: {
+        registry: Registry;
+        db: import("../db/index.js").DbConnection;
+        sseBroker: import("../api/sse-broker.js").SseBroker;
+        redis: import("ioredis").Redis;
+    }) => Record<string, unknown>);
+    /** Wire up auth routes (login, tenant-switch). Leave undefined to skip. */
+    authConfig?: AuthRoutesConfig;
+    /** Register a file storage provider so uploads via POST /api/files work and
+     *  `ctx.files.ref(key)` is available to hooks/MSPs. Omit to skip — tests
+     *  without file handling don't need it. */
+    files?: {
+        storageProvider: import("../files/index.js").FileStorageProvider;
+    };
+    /** Observability provider — omit for NoopProvider (no spans/metrics).
+     *  Pass a ConsoleProvider to see the span tree in stdout, or a custom
+     *  provider (e.g. a recording provider for assertions in tests). */
+    observability?: ObservabilityProvider;
+    /** Inject a process lifecycle so tests can drain() and observe
+     *  /health/ready flipping to 503. Omit if the suite doesn't care. */
+    lifecycle?: Lifecycle;
+    /** Wire L1 (global-IP) and/or L2 (auth-endpoint) rate-limit middleware.
+     *  The resolver is auto-built from the test Redis. Mirrors
+     *  buildServer's `rateLimit` option 1:1 — see there for shape. */
+    rateLimit?: import("../api/server.js").ServerOptions["rateLimit"];
+    /** Forwarded to buildServer — Integration-Tests that exercise `extraRoutes`
+     *  MUST go through here (real HTTP via `stack.http`/`stack.app.fetch`),
+     *  never `createTestDispatcher`. */
+    extraRoutes?: import("../api/server.js").ServerOptions["extraRoutes"];
+    /** Forwarded to buildServer like runProdApp. Without a PrometheusMeter-backed
+     *  `observability` the route answers 503, so spread `resolveObservabilityWiring(token)`
+     *  rather than setting `metrics` alone. */
+    metrics?: import("../api/server.js").ServerOptions["metrics"];
+    /** Inject a MasterKeyProvider for secrets-backed tests. Lands typed in
+     *  AppContext — set/delete/get + rotation job pick it up. Omit for
+     *  suites that don't touch secrets. */
+    masterKeyProvider?: import("../secrets/index.js").MasterKeyProvider;
+    /** Feature-toggle resolver. When present the dispatcher's feature-gate,
+     *  hook-filter, and MSP-filter all consult it; absent = every feature
+     *  treated as always-on. Pass the callback from
+     *  GlobalFeatureToggleRuntime.effectiveFeatures for real DB-backed
+     *  toggles, or a plain `() => new Set<string>(registry.features.keys())`
+     *  to force a specific snapshot in a unit-style setup. */
+    effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+    /** Pin the underlying Postgres DB name instead of the default
+     *  `kumiko_test_<8chars>`. Forwarded to createTestDb. Primary use
+     *  case: dev servers that want persistent storage across restarts —
+     *  combine with `persistentDb: true`. */
+    dbName?: string;
+    /** When true, cleanup() keeps the Postgres DB around — the caller
+     *  owns its lifecycle. Default false (test contract). Used by
+     *  dev-server wiring to survive hot-reloads. */
+    persistentDb?: boolean;
+    /** Forwarded to buildServer — when set, requests without a JWT pass
+     *  through as anonymous instead of 401. See AnonymousAccessConfig.
+     *  Akzeptiert entweder einen statischen Config-Object ODER eine Factory
+     *  `({registry, db, sseBroker, redis}) => Config` — gleiches Pattern wie
+     *  `extraContext`. Die Factory wird einmal beim Boot aufgerufen, der
+     *  TenantResolver darin closure'd typischerweise `db` für Subdomain-
+     *  Lookups. */
+    anonymousAccess?: import("../api/server.js").ServerOptions["anonymousAccess"] | ((deps: {
+        registry: Registry;
+        db: import("../db/index.js").DbConnection;
+        sseBroker: import("../api/sse-broker.js").SseBroker;
+        redis: import("ioredis").Redis;
+    }) => import("../api/server.js").ServerOptions["anonymousAccess"]);
+    /** Optional post-factory enricher (e.g. merge auth-foundation tenant
+     *  providers). Keeps framework free of a bundled-features dependency. */
+    enrichAnonymousAccess?: (base: import("../api/server.js").ServerOptions["anonymousAccess"] | undefined, deps: {
+        registry: Registry;
+        db: import("../db/index.js").DbConnection;
+    }) => Promise<import("../api/server.js").ServerOptions["anonymousAccess"] | undefined>;
+    /** Opt-in JobRunner wired into ctx.jobRunner and merged into
+     *  dispatcherOptions so event-triggered jobs enqueue on commit — mirrors
+     *  the prod entrypoint's `buildJobRunnerWithHook`. Unlike prod (which
+     *  always builds one), this only builds a runner when `registry.getAllJobs()`
+     *  is non-empty — a deliberate test-stack-only shortcut, not parity.
+     *  Default `undefined`. Pass `consumerLane` only when this test IS the
+     *  sole consumer (otherwise enqueuer-only, avoiding double-running
+     *  `runOnBoot`/cron jobs against a caller-owned consumer). */
+    jobs?: {
+        consumerLane?: JobRunIn;
+        /** Default: unique per stack, derived from its test Redis keyPrefix. Pass
+         *  the same value to every runner that has to share this stack's queues. */
+        queueNamePrefix?: string;
+        /** Source of active tenant ids for `perTenant: true` jobs. Omit when the
+         *  tenant feature is among `options.features` — the framework then
+         *  resolves tenants on its own via that feature's active-tenant-ids
+         *  query, same as prod. Only needed for suites that fan a job over
+         *  tenants without mounting the tenant feature. */
+        getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
+        /** Run-log callbacks (job_runs / tenant job failures), built once registry
+         *  and db exist. The framework can't import the bundled jobs feature, so the
+         *  dev-server wrapper supplies prod's `jobRunLoggerCallbacks` here. They are
+         *  awaited before drainJobs() observes the job's outcome. */
+        runLogger?: (deps: {
+            registry: Registry;
+            db: import("../db/index.js").DbConnection;
+        }) => Pick<JobRunnerOptions, "onJobStart" | "onJobComplete" | "onJobFailed"> | undefined;
+    };
+    /** Override the event dispatcher's polling-timer interval. Default 50ms.
+     *  Tests that assert LISTEN/NOTIFY wake-up latency need this pushed far
+     *  out (e.g. 60_000) so the polling timer can't land inside the
+     *  assertion window and mask a dead subscription — see E.4 (#2042). */
+    eventDispatcherPollIntervalMs?: number;
+    /** Opt out of auto-created r.entity() tables for callers that create/migrate
+     *  them themselves. Default true — false pushes only projection/MSP/
+     *  storeTable sources, same as before fw#3102. */
+    entityTables?: boolean;
+    /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
+     *  — see there. Default 0. */
+    trustedProxyHops?: number;
+};
+export declare function setupTestStack(options: TestStackOptions): Promise<TestStack>;