@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/stack/test-stack.ts

@@ -2,14 +2,15 @@ import type { Hono } from "hono";
 import type { AuthRoutesConfig } from "../api/auth-routes";
 import type { JwtHelper } from "../api/jwt";
 import { buildServer } from "../api/server";
-import { createSseBroker } from "../api/sse-broker";
+import { createSseBroker, type SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import { extractTableInfo } from "../db/query";
 import { createRegistry } from "../engine/registry";
-import type { FeatureDefinition, Registry, TenantId } from "../engine/types";
+import type { FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
+import { createJobRunner, type JobRunner } from "../jobs";
 import type { Lifecycle } from "../lifecycle";
-import type { ObservabilityProvider } from "../observability";
+import { createNoopProvider, type ObservabilityProvider } from "../observability";
 import type { Dispatcher, EventDispatcher } from "../pipeline";
 import { createEntityCache, createEventDedup, createIdempotencyGuard } from "../pipeline";
 import { createInMemorySearchAdapter } from "../search";
@@ -24,13 +25,17 @@ export type TestStack = {
   app: Hono;
   jwt: JwtHelper;
   registry: Registry;
-  // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
-  db: any;
+  db: import("../db").DbConnection;
   redis: TestRedis;
   search: SearchAdapter;
   events: EventCollector;
   http: RequestHelper;
   observability: ObservabilityProvider;
+  // In-memory broker backing the server's SSE routes + access-invalidation
+  // channel. Tests subscribe directly (e.g. sseBroker.subscribeAccessInvalidation)
+  // to assert a consumer pushed an invalidation without opening a real SSE
+  // connection.
+  sseBroker: SseBroker;
   // Command-dispatcher behind the HTTP routes — for direct system-writes
   // in tests and dev-server extraRoutes (provider-webhook wiring).
   dispatcher: Dispatcher;
@@ -41,6 +46,10 @@ export type TestStack = {
   // Only set when the caller passed `lifecycle` via options. Tests that
   // exercise drain() / /health/ready wire one in; ordinary suites ignore it.
   lifecycle?: Lifecycle;
+  // Only set when `options.jobs` is truthy AND ≥1 `r.job(...)` is
+  // registered in the mounted features. Lets integration tests call
+  // `stack.jobRunner.dispatch(...)` directly, mirroring `ctx.jobRunner`.
+  jobRunner?: JobRunner;
   cleanup: () => Promise<void>;
 };
 
@@ -61,8 +70,7 @@ export type TestStackOptions = {
     | Record<string, unknown>
     | ((deps: {
         registry: Registry;
-        // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
-        db: any;
+        db: import("../db").DbConnection;
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => Record<string, unknown>);
@@ -114,11 +122,31 @@ export type TestStackOptions = {
     | import("../api/server").ServerOptions["anonymousAccess"]
     | ((deps: {
         registry: Registry;
-        // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
-        db: any;
+        db: import("../db").DbConnection;
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => import("../api/server").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").ServerOptions["anonymousAccess"] | undefined,
+    deps: {
+      registry: Registry;
+      db: import("../db").DbConnection;
+    },
+  ) => Promise<import("../api/server").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;
+    queueNamePrefix?: string;
+  };
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
@@ -213,40 +241,8 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   const events = createEventCollector();
   const registry = createRegistry([...options.features]);
 
-  // Auto-configure search for tenant 1 based on registry
-  if (enabledHooks.includes("search")) {
-    const searchableFields: string[] = [];
-    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,
-      });
-    }
-  }
-
-  // Wire SSE broker with event collector
+  // 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",
@@ -254,8 +250,6 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     () => {},
   );
 
-  const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
-  const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
   const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
 
   // A static `files.storageProvider` is wired as the per-tenant resolver — the
@@ -267,97 +261,221 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     fileProviderResolver = () => Promise.resolve(provider);
   }
 
-  const server = buildServer({
+  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,
-    context: {
-      db: testDb.db,
-      redis: testRedis.redis,
-      searchAdapter,
-      entityCache,
+    ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
+    ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
+    ...(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: JobRunner | undefined;
+  if (options.jobs && registry.getAllJobs().size > 0) {
+    jobRunner = createJobRunner({
       registry,
-      ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
-      ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
-      ...(typeof options.extraContext === "function"
-        ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
-        : options.extraContext),
-    },
-    jwtSecret,
-    dispatcherOptions: {
-      idempotency,
-      ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
-    },
-    eventDedup,
-    sseBroker,
-    // 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: 50,
-      pgClient: testDb.client as PgClient | undefined,
-      systemConsumers: {
-        sse: enabledHooks.includes("sse"),
-        search: enabledHooks.includes("search"),
-      },
-    },
-    // 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.observability ? { observability: options.observability } : {}),
-    ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
-    ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
-    ...(options.anonymousAccess
-      ? {
-          anonymousAccess:
-            typeof options.anonymousAccess === "function"
-              ? options.anonymousAccess({
-                  registry,
-                  db: testDb.db,
-                  sseBroker,
-                  redis: testRedis.redis,
-                })
-              : options.anonymousAccess,
+      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 }),
+      ...(options.jobs.queueNamePrefix !== undefined && {
+        queueNamePrefix: options.jobs.queueNamePrefix,
+      }),
+    });
+  }
+
+  // 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: string[] = [];
+      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}`);
+                }
+              }
+            }
+          }
         }
-      : {}),
-  });
+      }
 
-  const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
+      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,
+        });
+      }
+    }
 
-  // Pre-register consumer state rows so tests can call runOnce() directly
-  // without a preceding explicit start(). Timer fires at pollIntervalMs=50
-  // but passInFlight serialises concurrent passes — 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 idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
+    const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
 
-  const http = createRequestHelper(server.app, server.jwt);
+    const server = buildServer({
+      registry,
+      context: appContext,
+      jwtSecret,
+      ...(options.observability ? { observability: options.observability } : {}),
+      dispatcherOptions: {
+        idempotency,
+        ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
+        ...(jobRunner && { jobRunner }),
+      },
+      eventDedup,
+      sseBroker,
+      // 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: 50,
+        pgClient: testDb.client as PgClient | undefined,
+        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 } : {};
+      })()),
+    });
 
-  return {
-    app: server.app,
-    jwt: server.jwt,
-    registry,
-    db: testDb.db,
-    redis: testRedis,
-    search: searchAdapter,
-    events,
-    http,
-    observability: server.observability,
-    dispatcher: server.dispatcher,
-    ...(eventDispatcher ? { eventDispatcher } : {}),
-    ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
-    cleanup: async () => {
-      if (eventDispatcher) await eventDispatcher.stop();
-      await server.observability.shutdown();
-      await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
-    },
-  };
+    const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
+
+    // Pre-register consumer state rows so tests can call runOnce() directly
+    // without a preceding explicit start(). Timer fires at pollIntervalMs=50
+    // but passInFlight serialises concurrent passes — 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,
+      ...(eventDispatcher ? { eventDispatcher } : {}),
+      ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
+      ...(jobRunner ? { jobRunner } : {}),
+      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/src/testing/__tests__/late-bound.test.ts

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

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

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

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

@@ -0,0 +1,121 @@
+import { SEARCHABLE_FALSE_WHITELIST } from "../engine/boot-validator/entity-list-screens";
+import { normalizeListColumn } from "../engine/screen-helpers";
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+  FeatureDefinition,
+  TranslationEntry,
+} from "../engine/types";
+import { featureHasI18nSurface, requiredKeysFromFeature } from "../i18n/required-surface-keys";
+
+function ensureEntityListSortable(feature: FeatureDefinition): FeatureDefinition {
+  if (!feature.entities) return feature;
+  const entities: Record<string, EntityDefinition> = { ...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: FeatureDefinition,
+  screen: EntityListScreenDefinition,
+): EntityListScreenDefinition {
+  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 ?? []),
+      {
+        kind: "navigate",
+        id: "edit",
+        label: "stub:edit",
+        screen: editScreen.id,
+        params: { pick: ["id"] },
+      },
+    ],
+  };
+}
+
+function defaultSortForEntityList(
+  feature: FeatureDefinition,
+  screen: EntityListScreenDefinition,
+): EntityListScreenDefinition {
+  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" as const } };
+}
+
+function stubTranslations(feature: FeatureDefinition): FeatureDefinition {
+  if (!featureHasI18nSurface(feature)) return feature;
+  const keys: Record<string, TranslationEntry> = {
+    ...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: readonly FeatureDefinition[],
+): FeatureDefinition[] {
+  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 });
+  });
+}