@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/stack/test-stack.js

@@ -0,0 +1,398 @@
+import { buildServer } from "../api/server.js";
+import { createSseBroker } from "../api/sse-broker.js";
+import { validateOwnershipBoot } from "../engine/boot-validator/ownership.js";
+import { createRegistry } from "../engine/registry.js";
+import { createArchivedStreamsTable, createEventsTable } from "../event-store/index.js";
+import { createJobRunner } from "../jobs/index.js";
+import { createNoopProvider } from "../observability/index.js";
+import { createEntityCache, createEventDedup, createIdempotencyGuard, dispatcherToWriteRef, } from "../pipeline/index.js";
+import { createRateLimitResolver } from "../rate-limit/index.js";
+import { createInMemorySearchAdapter } from "../search/index.js";
+import { createTestDb } from "./db.js";
+import { createJobFailureTracker, drainJobs } from "./drain-jobs.js";
+import { createEventCollector } from "./event-collector.js";
+import { createTestRedis } from "./redis.js";
+import { createRequestHelper } from "./request-helper.js";
+import { unsafePushTables } from "./table-helpers.js";
+const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
+// BullMQ queues live on the raw redisUrl, outside the test Redis keyPrefix, so
+// parallel stacks sharing the prod default queue name would consume each
+// other's jobs. BullMQ rejects `:` in queue names.
+function queueNamePrefixForTestRedis(keyPrefix) {
+    return keyPrefix.split(":").filter(Boolean).join("-");
+}
+export async function setupTestStack(options) {
+    const jwtSecret = options.jwtSecret ?? DEFAULT_JWT_SECRET;
+    const enabledHooks = options.systemHooks ?? ["sse", "search"];
+    // Temporal-Polyfill installieren bevor Feature-Code läuft. Idempotent —
+    // Production-Server-Boot ruft das gleich. Auf Runtimes mit nativem
+    // Temporal ein No-Op.
+    const { ensureTemporalPolyfill } = await import("../time/polyfill.js");
+    await ensureTemporalPolyfill();
+    // Ownership boot-guards (fw#2639 unqualified where-fragments, fw#2626
+    // where-rules on the write path) otherwise run only in the prod boot via
+    // validateBoot, leaving every test stack blind to a broken access map.
+    // Runs after the polyfill (buildEntityTable needs it to derive the probe
+    // columns) and before the ephemeral DB/Redis exist, so a throw can't leak
+    // a database that nothing will clean up.
+    validateOwnershipBoot(options.features);
+    // Forward db-name/persistent-flag through to createTestDb. The
+    // defaults (undefined dbName, persistent:false) keep the legacy
+    // test contract: fresh kumiko_test_<random> DB per setup, dropped
+    // on cleanup.
+    const [testDb, testRedis] = await Promise.all([
+        createTestDb({
+            ...(options.dbName !== undefined && { dbName: options.dbName }),
+            ...(options.persistentDb !== undefined && { persistent: options.persistentDb }),
+        }),
+        createTestRedis(),
+    ]);
+    // Any throw in this DDL region must still drop the just-created ephemeral
+    // DB/Redis — the caller never gets the stack object back to call
+    // cleanup() itself (same "leaked ephemeral DB" failure class as the later
+    // try/catch below, but for setup that runs before that try starts).
+    try {
+        // Every ES-entity writes events via createEventStoreExecutor in the
+        // feature's write handlers. Auto-create the events table so every
+        // setupTestStack call is ready for writes without needing a manual
+        // createEventsTable().
+        await createEventsTable(testDb.db);
+        // Archive-stream metadata — needed by ctx.appendEvent's archive guard and
+        // loadAggregate's default-skip. Idempotent, so production boot running
+        // the same call is fine.
+        await createArchivedStreamsTable(testDb.db);
+        // Framework state for projection rebuild/status + event-consumer cursors.
+        // Idempotent — production boot flows run the same calls.
+        const { createProjectionStateTable, createEventConsumerStateTable } = await import("../pipeline/index.js");
+        await createProjectionStateTable(testDb.db);
+        await createEventConsumerStateTable(testDb.db);
+        // Files support: when a provider is registered, the fileRefs table must
+        // exist before the first upload. Skipped when no provider — the table
+        // stays off tenant test DBs that never touch files.
+        if (options.files) {
+            const { fileRefsTable } = await import("../files/index.js");
+            await unsafePushTables(testDb.db, { fileRefsTable });
+        }
+        // Same table list as `kumiko schema generate` (collectTableMetas) — divergence
+        // was the #255 prod-crash and the #3102 missing r.entity() tables.
+        const { collectTableMetas } = await import("../db/collect-table-metas.js");
+        const { tableExists } = await import("../db/schema-inspection.js");
+        let metas = collectTableMetas(options.features);
+        if (options.entityTables === false) {
+            const { enumerateFeatureTableSources } = await import("../db/feature-table-sources.js");
+            const { extractTableInfo } = await import("../db/query.js");
+            const nonEntityNames = new Set(options.features.flatMap((f) => enumerateFeatureTableSources(f).map((s) => extractTableInfo(s.table).name)));
+            metas = metas.filter((m) => nonEntityNames.has(m.tableName));
+        }
+        const missing = {};
+        for (const meta of metas) {
+            if (await tableExists(testDb.db, `public.${meta.tableName}`))
+                continue;
+            missing[meta.tableName] = meta;
+        }
+        if (Object.keys(missing).length > 0) {
+            await unsafePushTables(testDb.db, missing);
+        }
+    }
+    catch (error) {
+        try {
+            await testDb.cleanup();
+        }
+        catch {
+            // ignore — `error` is the one that matters
+        }
+        try {
+            await testRedis.cleanup();
+        }
+        catch {
+            // ignore — `error` is the one that matters
+        }
+        throw error;
+    }
+    const searchAdapter = createInMemorySearchAdapter();
+    const events = createEventCollector();
+    const registry = createRegistry([...options.features]);
+    // Wire SSE broker with event collector — built early (not just before
+    // buildServer) because extraContext + the job context below both need it.
+    const sseBroker = createSseBroker();
+    sseBroker.addClient("tenant:00000000-0000-4000-8000-000000000001", (event) => events.sse.push(event), () => { });
+    const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
+    // A static `files.storageProvider` is wired as the per-tenant resolver — the
+    // framework test seam that doesn't require mounting config + file-foundation.
+    // (Bundled GDPR tests mount the real provider features instead.)
+    let fileProviderResolver;
+    if (options.files) {
+        const provider = options.files.storageProvider;
+        fileProviderResolver = () => Promise.resolve(provider);
+    }
+    const observability = options.observability ?? createNoopProvider();
+    // Same AppContext buildServer() gets below (db/redis/searchAdapter/
+    // entityCache/masterKeyProvider/fileProviderResolver/extraContext) —
+    // shared so the job context can't drift from the request-path context
+    // (kumiko-framework#1232: a reduced `{ db, registry }` literal let jobs
+    // pass in tests while reaching for fields only prod's context has).
+    //
+    // effectiveFeatures deliberately stays OUT of appContext — prod never puts
+    // it there either (only dispatcherOptions.effectiveFeatures, consumed by
+    // the command-dispatcher — see buildJobRunnerWithHook in entrypoint/
+    // index.ts). Putting it here would reintroduce the exact test-vs-prod
+    // drift #1232 fixed: a job/handler reading `ctx.effectiveFeatures` would
+    // pass in tests and break in prod (kumiko-framework#1255).
+    const appContext = {
+        db: testDb.db,
+        redis: testRedis.redis,
+        searchAdapter,
+        entityCache,
+        registry,
+        ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
+        ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
+        ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
+        ...(typeof options.extraContext === "function"
+            ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
+            : options.extraContext),
+    };
+    // Built before buildServer() so it can be merged into dispatcherOptions
+    // (write handlers' `ctx.jobRunner.dispatch(...)` and the afterCommit
+    // event-trigger hook both need it present at dispatcher-construction
+    // time, same as the prod entrypoint's buildJobRunnerWithHook). Uses the
+    // test-stack's own ephemeral redis — no separate `redisUrl` seam needed.
+    //
+    // context = appContext + tracer/meter, mirroring the prod entrypoint's
+    // `contextWithObservability(options.context, observability)`.
+    let jobRunner;
+    // Fed to createJobRunner's onJobComplete/onJobFailed below so drainJobs()
+    // can tell a job's final outcome apart from an attempt that will retry —
+    // built before createJobRunner regardless of whether a runner ends up
+    // existing, so the returned drainJobs() closure always has one to read.
+    const jobFailureTracker = createJobFailureTracker();
+    if (options.jobs && registry.getAllJobs().size > 0) {
+        const runLogger = options.jobs.runLogger?.({ registry, db: testDb.db });
+        jobRunner = createJobRunner({
+            registry,
+            context: { ...appContext, tracer: observability.tracer, meter: observability.meter },
+            // The real REDIS_URL, not one rebuilt from `.options` — that lost
+            // password/username/tls/path (pr-review kumiko-framework #1036/2).
+            redisUrl: testRedis.redisUrl,
+            ...(options.jobs.consumerLane !== undefined && { consumerLane: options.jobs.consumerLane }),
+            queueNamePrefix: options.jobs.queueNamePrefix ?? queueNamePrefixForTestRedis(testRedis.keyPrefix),
+            ...(options.jobs.getActiveTenantIds !== undefined && {
+                getActiveTenantIds: options.jobs.getActiveTenantIds,
+            }),
+            ...(runLogger?.onJobStart !== undefined && { onJobStart: runLogger.onJobStart }),
+            // Tracker fires in finally: drainJobs wakes on it, so the log row must
+            // be written first, and a throwing logger must not swallow the signal.
+            onJobComplete: async (jobName, jobId, ...rest) => {
+                try {
+                    await runLogger?.onJobComplete?.(jobName, jobId, ...rest);
+                }
+                finally {
+                    jobFailureTracker.onJobComplete(jobName, jobId);
+                }
+            },
+            onJobFailed: async (jobName, jobId, error, ...rest) => {
+                try {
+                    await runLogger?.onJobFailed?.(jobName, jobId, error, ...rest);
+                }
+                finally {
+                    jobFailureTracker.onJobFailed(jobName, jobId, error);
+                }
+            },
+        });
+    }
+    // From here on, any throw must stop a jobRunner that was already created
+    // above (createJobRunner() itself opens live BullMQ Queue/lock Redis
+    // connections, .start() adds a live worker) — otherwise a failing
+    // buildServer()/search-config/etc. leaks that connection and the test
+    // process hangs on exit (pr-review kumiko-framework #1036/1).
+    try {
+        if (jobRunner)
+            await jobRunner.start();
+        // Auto-configure search for tenant 1 based on registry
+        if (enabledHooks.includes("search")) {
+            const searchableFields = [];
+            for (const feature of options.features) {
+                for (const [, entity] of Object.entries(feature.entities ?? {})) {
+                    for (const [fieldName, field] of Object.entries(entity.fields)) {
+                        if (field.type === "text" && field.searchable) {
+                            searchableFields.push(fieldName);
+                        }
+                        if (field.type === "embedded") {
+                            for (const [subName, subField] of Object.entries(field.schema)) {
+                                if (subField.searchable) {
+                                    searchableFields.push(`${fieldName}_${subName}`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            if (options.searchConfig) {
+                await searchAdapter.configure(options.searchConfig.tenantId, {
+                    searchableFields: options.searchConfig.searchableFields,
+                    rankingFields: options.searchConfig.rankingFields,
+                });
+            }
+            else if (searchableFields.length > 0) {
+                await searchAdapter.configure("00000000-0000-4000-8000-000000000001", {
+                    searchableFields,
+                    rankingFields: searchableFields,
+                });
+            }
+        }
+        const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
+        const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
+        // buildServer only auto-wires an L3 RateLimitResolver from
+        // `context.redis` — a degradation test that nulls `redis` via
+        // extraContext (to exercise a handler's own ctx.redis-down guard) also
+        // silently strips rate-limiting, even though every handler with a
+        // `rateLimit` declaration still requires a resolver at dispatch time.
+        // Since e7bf543ad, an IP-keyed bucket key is built unconditionally
+        // (falls back to a shared "unknown" IP rather than skipping), so the
+        // missing resolver now throws instead of merely skipping enforcement.
+        // Mirrors idempotency/eventDedup above: built from the test-stack's own
+        // always-real `testRedis.redis`, independent of whatever extraContext
+        // did to `appContext.redis` — an explicit `context.rateLimit` from
+        // extraContext still wins (same precedence buildServer documents).
+        // @cast-boundary extraContext is declared Record<string, unknown> (late,
+        // dynamic extension point) — appContext's inferred type doesn't carry a
+        // `rateLimit` key, so reading it back needs the same relaxed boundary
+        // extraContext itself is typed with.
+        const explicitRateLimit = appContext.rateLimit;
+        const rateLimitFallback = appContext.redis === undefined && explicitRateLimit === undefined
+            ? createRateLimitResolver({ redis: testRedis.redis })
+            : undefined;
+        const server = buildServer({
+            registry,
+            context: rateLimitFallback ? { ...appContext, rateLimit: rateLimitFallback } : appContext,
+            jwtSecret,
+            ...(options.observability ? { observability: options.observability } : {}),
+            dispatcherOptions: {
+                idempotency,
+                ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
+                ...(jobRunner && { jobRunner }),
+            },
+            eventDedup,
+            sseBroker,
+            ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
+            ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
+            ...(options.metrics && { metrics: options.metrics }),
+            // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
+            // deterministic drains — no timer-induced flakiness. pollIntervalMs
+            // stays short anyway in case a test opts into `.start()`. pgClient
+            // plumbs through the LISTEN wake-up for tests that want to measure
+            // post-commit latency (Sprint E.4).
+            eventDispatcher: {
+                pollIntervalMs: options.eventDispatcherPollIntervalMs ?? 50,
+                pgClient: testDb.client,
+                systemConsumers: {
+                    sse: enabledHooks.includes("sse"),
+                    search: enabledHooks.includes("search"),
+                    accessInvalidation: enabledHooks.includes("sse"),
+                },
+            },
+            // Default tests to no login rate-limiter so existing suites that loop
+            // over logins don't hit a 429 after 10 attempts. Suites specifically
+            // testing the limiter can override via authConfig.loginRateLimit.
+            ...(options.authConfig
+                ? {
+                    auth: {
+                        ...options.authConfig,
+                        ...(options.authConfig.loginRateLimit === undefined ? { loginRateLimit: null } : {}),
+                    },
+                }
+                : {}),
+            ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
+            ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
+            ...(await (async () => {
+                const baseAnon = typeof options.anonymousAccess === "function"
+                    ? options.anonymousAccess({
+                        registry,
+                        db: testDb.db,
+                        sseBroker,
+                        redis: testRedis.redis,
+                    })
+                    : options.anonymousAccess;
+                const resolvedAnon = options.enrichAnonymousAccess
+                    ? await options.enrichAnonymousAccess(baseAnon, {
+                        registry,
+                        db: testDb.db,
+                    })
+                    : baseAnon;
+                return resolvedAnon ? { anonymousAccess: resolvedAnon } : {};
+            })()),
+        });
+        // Mirrors the prod entrypoints — without this, JobContext.write/writeAs/
+        // queryAs/queryAsMember throw on first use inside a test-stack job.
+        if (jobRunner)
+            jobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
+        const eventDispatcher = server.eventDispatcher;
+        // Pre-register consumer state rows so tests can call runOnce() directly
+        // without a preceding explicit start(). Timer fires at pollIntervalMs=50
+        // but each consumer runs at most one turn at a time — tests that drain via
+        // runOnce() remain deterministic. Tests that specifically exercise the
+        // timer loop call start() again (idempotent) after setup.
+        if (eventDispatcher)
+            await eventDispatcher.ensureRegistered();
+        const http = createRequestHelper(server.app, server.jwt, {
+            ...(options.authConfig?.sessionCreator !== undefined && {
+                sessionCreator: options.authConfig.sessionCreator,
+            }),
+        });
+        return {
+            app: server.app,
+            jwt: server.jwt,
+            registry,
+            db: testDb.db,
+            redis: testRedis,
+            search: searchAdapter,
+            events,
+            http,
+            observability: server.observability,
+            sseBroker,
+            dispatcher: server.dispatcher,
+            context: server.context,
+            ...(eventDispatcher ? { eventDispatcher } : {}),
+            ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
+            ...(jobRunner ? { jobRunner } : {}),
+            drainJobs: () => drainJobs({ db: testDb.db, eventDispatcher, jobRunner }, jobFailureTracker),
+            cleanup: async () => {
+                if (jobRunner)
+                    await jobRunner.stop();
+                if (eventDispatcher)
+                    await eventDispatcher.stop();
+                await server.observability.shutdown();
+                await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
+            },
+        };
+    }
+    catch (error) {
+        // Best-effort — a broken jobRunner.stop()/cleanup() must never mask the
+        // real setup failure below. testDb/testRedis are created before this
+        // try even starts, so a throw anywhere in setup (buildServer,
+        // search-config, ...) would otherwise leak their open pg/ioredis
+        // sockets — the caller never gets the stack object back to call
+        // cleanup() itself, which is the same "hangs on exit" failure class
+        // this function exists to prevent.
+        if (jobRunner) {
+            try {
+                await jobRunner.stop();
+            }
+            catch {
+                // ignore — `error` is the one that matters
+            }
+        }
+        try {
+            await testDb.cleanup();
+        }
+        catch {
+            // ignore — `error` is the one that matters
+        }
+        try {
+            await testRedis.cleanup();
+        }
+        catch {
+            // ignore — `error` is the one that matters
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,33 @@
+import type { SessionUser, TenantId } from "../engine/types/index.js";
+export declare function testTenantId(n: number): TenantId;
+export declare function testUserId(n: number): string;
+export declare const TestUsers: {
+    readonly admin: {
+        readonly id: string;
+        readonly tenantId: string;
+        readonly roles: readonly ["Admin"];
+    };
+    readonly systemAdmin: {
+        readonly id: string;
+        readonly tenantId: string;
+        readonly roles: readonly ["SystemAdmin"];
+    };
+    readonly user: {
+        readonly id: string;
+        readonly tenantId: string;
+        readonly roles: readonly ["User"];
+    };
+    readonly driver: {
+        readonly id: string;
+        readonly tenantId: string;
+        readonly roles: readonly ["Driver"];
+    };
+    readonly otherTenant: {
+        readonly id: string;
+        readonly tenantId: string;
+        readonly roles: readonly ["Admin"];
+    };
+};
+export declare function createTestUser(overrides?: Partial<Omit<SessionUser, "id">> & {
+    id?: string | number;
+}): SessionUser;

package/dist/stack/test-users.js

@@ -0,0 +1,29 @@
+// Zero-padded UUIDs used across the test suite. `testTenantId(1)` /
+// `testUserId(1)` read cleaner in assertions than the full UUID literals,
+// and keep all tests on a single shape — if the UUID layout ever changes,
+// it changes here.
+export function testTenantId(n) {
+    return `00000000-0000-4000-8000-${n.toString().padStart(12, "0")}`;
+}
+// Distinct prefix from tenantId so debug output visibly differentiates the
+// two when a user-id accidentally lands in a tenant-id slot.
+export function testUserId(n) {
+    return `11111111-0000-4000-8000-${n.toString().padStart(12, "0")}`;
+}
+export const TestUsers = {
+    admin: { id: testUserId(1), tenantId: testTenantId(1), roles: ["Admin"] },
+    systemAdmin: { id: testUserId(1), tenantId: testTenantId(1), roles: ["SystemAdmin"] },
+    user: { id: testUserId(2), tenantId: testTenantId(1), roles: ["User"] },
+    driver: { id: testUserId(3), tenantId: testTenantId(1), roles: ["Driver"] },
+    otherTenant: { id: testUserId(10), tenantId: testTenantId(2), roles: ["Admin"] },
+};
+// Accept numeric shortcuts for legacy call sites — stringify to a UUID so the
+// SessionUser type stays aligned. `createTestUser({ id: 42 })` gives you
+// `testUserId(42)`. Explicit strings pass through untouched.
+export function createTestUser(overrides) {
+    const normalizedId = typeof overrides?.id === "number"
+        ? testUserId(overrides.id)
+        : (overrides?.id ?? TestUsers.admin.id);
+    const { id: _id, ...rest } = overrides ?? {};
+    return { ...TestUsers.admin, ...rest, id: normalizedId };
+}

package/dist/testing/access-assertions.d.ts

@@ -0,0 +1,2 @@
+import type { AccessRule } from "../engine/types/index.js";
+export declare function rolesOf(access: AccessRule | undefined): readonly string[];

package/dist/testing/access-assertions.js

@@ -0,0 +1,13 @@
+// Test-only helper: extracts the role list from a role-based AccessRule,
+// narrowing the union safely. Throws when the rule is openToAll or missing —
+// the tests that call this always expect roles, and a clear error beats a
+// cryptic undefined assertion downstream.
+export function rolesOf(access) {
+    if (!access) {
+        throw new Error("expected role-based access rule, got undefined");
+    }
+    if (!("roles" in access)) {
+        throw new Error("expected role-based access rule, got openToAll");
+    }
+    return access.roles;
+}

package/dist/testing/assertions.d.ts

@@ -0,0 +1,10 @@
+import type { WriteResult } from "../engine/types/index.js";
+import type { WriteErrorInfo } from "../errors/index.js";
+export declare function expectSuccess<T>(result: WriteResult<T>): asserts result is {
+    isSuccess: true;
+    data: T;
+};
+export declare function expectError(result: WriteResult, matcher?: string): asserts result is {
+    isSuccess: false;
+    error: WriteErrorInfo;
+};

package/dist/testing/assertions.js

@@ -0,0 +1,22 @@
+export function expectSuccess(result) {
+    if (!result.isSuccess) {
+        throw new Error(`Expected success but got error: ${result.error.code} (${result.error.message})`);
+    }
+}
+// `matcher` checks either the error code (e.g. "not_found") or looks for a
+// substring in the message. Both are useful: code matches are stable across
+// i18n changes, substrings catch feature-specific detail text.
+export function expectError(result, matcher) {
+    if (result.isSuccess) {
+        throw new Error("Expected error but got success");
+    }
+    if (matcher === undefined) {
+        // skip: caller only asked for the type narrowing; nothing else to check.
+        return;
+    }
+    const err = result.error;
+    const hit = err.code === matcher || err.message.includes(matcher);
+    if (!hit) {
+        throw new Error(`Expected error code or message to match "${matcher}" but got code="${err.code}", message="${err.message}"`);
+    }
+}

package/dist/testing/boot-validator-fixture.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureDefinition } from "../engine/types/index.js";
+/** Test-fixture helper: satisfy entityList + i18n boot rules without bloating every makeFeature. */
+export declare function withBootValidatorFixture(features: readonly FeatureDefinition[]): FeatureDefinition[];

package/dist/testing/boot-validator-fixture.js

@@ -0,0 +1,101 @@
+import { SEARCHABLE_FALSE_WHITELIST } from "../engine/boot-validator/entity-list-screens.js";
+import { normalizeListColumn } from "../engine/screen-helpers.js";
+import { featureHasI18nSurface, requiredKeysFromFeature } from "../i18n/required-surface-keys.js";
+function ensureEntityListSortable(feature) {
+    if (!feature.entities)
+        return feature;
+    const entities = { ...feature.entities };
+    for (const screen of Object.values(feature.screens)) {
+        if (screen.type !== "entityList")
+            continue;
+        const entity = entities[screen.entity];
+        if (!entity)
+            continue;
+        const hasSortable = Object.values(entity.fields).some((field) => "sortable" in field && field.sortable === true);
+        if (hasSortable)
+            continue;
+        const firstCol = screen.columns[0];
+        if (firstCol === undefined)
+            continue;
+        const fieldName = normalizeListColumn(firstCol).field;
+        const fieldDef = entity.fields[fieldName];
+        if (fieldDef === undefined)
+            continue;
+        if (fieldDef.type !== "text" && fieldDef.type !== "number")
+            continue;
+        entities[screen.entity] = {
+            ...entity,
+            fields: {
+                ...entity.fields,
+                [fieldName]: { ...fieldDef, sortable: true },
+            },
+        };
+    }
+    return { ...feature, entities };
+}
+function ensureEntityListRowNavigation(feature, screen) {
+    const hasEdit = Object.values(feature.screens).some((s) => s.type === "entityEdit" && s.entity === screen.entity);
+    if (!hasEdit)
+        return screen;
+    const hasNavigate = (screen.rowActions ?? []).some((a) => a.kind === "navigate" && (a.id === "view" || a.id === "edit"));
+    if (hasNavigate)
+        return screen;
+    const editScreen = Object.values(feature.screens).find((s) => s.type === "entityEdit" && s.entity === screen.entity);
+    if (editScreen === undefined)
+        return screen;
+    return {
+        ...screen,
+        rowActions: [
+            ...(screen.rowActions ?? []),
+            // No `params` here: this same-entity target always resolves to
+            // UPDATE mode (the renderer auto-fills entityId from row["id"]),
+            // and entityEdit-update never reads search-params as initial
+            // values — the boot-validator now rejects that combination (#1680).
+            {
+                kind: "navigate",
+                id: "edit",
+                label: "stub:edit",
+                screen: editScreen.id,
+            },
+        ],
+    };
+}
+function defaultSortForEntityList(feature, screen) {
+    if (screen.defaultSort !== undefined || screen.searchable === false)
+        return screen;
+    if (SEARCHABLE_FALSE_WHITELIST.has(screen.id))
+        return screen;
+    const entity = feature.entities?.[screen.entity];
+    const sortableColumn = screen.columns.map(normalizeListColumn).find((col) => {
+        const fieldDef = entity?.fields[col.field];
+        return fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
+    });
+    if (sortableColumn === undefined)
+        return screen;
+    return { ...screen, defaultSort: { field: sortableColumn.field, dir: "asc" } };
+}
+function stubTranslations(feature) {
+    if (!featureHasI18nSurface(feature))
+        return feature;
+    const keys = {
+        ...Object.fromEntries(Object.entries(feature.translations ?? {}).map(([key, value]) => [key, { ...value }])),
+    };
+    for (const key of requiredKeysFromFeature(feature)) {
+        if (keys[key] === undefined)
+            keys[key] = { de: "stub", en: "stub" };
+    }
+    return { ...feature, translations: keys };
+}
+/** Test-fixture helper: satisfy entityList + i18n boot rules without bloating every makeFeature. */
+export function withBootValidatorFixture(features) {
+    return features.map((feature) => {
+        const sortable = ensureEntityListSortable(feature);
+        const screens = Object.fromEntries(Object.entries(sortable.screens).map(([id, screen]) => {
+            if (screen.type !== "entityList")
+                return [id, screen];
+            const withDefaults = defaultSortForEntityList(sortable, screen);
+            return [id, ensureEntityListRowNavigation(sortable, withDefaults)];
+        }));
+        return stubTranslations({ ...sortable, screens });
+    });
+}

package/dist/testing/closed-connection-error.d.ts

@@ -0,0 +1,7 @@
+export declare function testDatabaseUrl(): string;
+type AdminClient = {
+    unsafe(sql: string, params?: readonly unknown[]): Promise<unknown>;
+};
+export declare function terminateBackendsByApplicationName(admin: AdminClient, applicationName: string): Promise<void>;
+export declare function captureClosedConnectionError(url?: string): Promise<unknown>;
+export {};