@cosmicdrift/kumiko-testing 0.313.0 → 0.315.0

package/README.md

@@ -47,8 +47,17 @@ test("member sees the note", async ({ seedTenant, page }) => {
 - The template also sets `KUMIKO_DEV_STYLESHEET_WATCH=0`, so the dev-server builds the app's CSS once and
   never starts a Tailwind `--watch` process — that watcher would otherwise treat every Playwright artifact
   write under `test-results/` as a rebuild trigger.
-- App roles: `createE2eSeedRoutes({ extraRoles: ["TenantMember"] })` lets `tenant.addUser(["TenantMember"])` seed them;
-  `SystemAdmin` is never seedable and makes the route builder throw.
+- App roles: `createE2eSeedRoutes({ extraRoles: ["TenantMember"] })` lets `tenant.addUser(["TenantMember"])` seed them.
+- `tenant.addUser(["SystemAdmin"])` seeds a platform operator for SysAdmin screens: `SystemAdmin` lands as a
+  global user role, and the user joins the tenant as `Member` unless you also pass a tenant role
+  (`["TenantAdmin", "SystemAdmin"]`). The seed gate above is the only boundary around this.
+- App seeders for test data the seeded users can't create:
+  `createE2eSeedRoutes({ extraSeeders: { checks: async (ctx, tenantId, body) => … } })`, called from a flow as
+  `await tenant.seed("checks", { days: 30 })`. The seeder gets `body` as `unknown` (validate it with a zod
+  `parse`; a `ZodError` becomes a 400) and a `ctx` whose `write`/`query` run as the tenant's system user
+  (SystemAdmin), bound to that one tenant, so the target handler must admit SystemAdmin (data no normal
+  handler produces, like backdated history, needs a SystemAdmin-only handler). There is no raw DB access.
+  Only tenants seeded by the same server's seed-tenant route are accepted; unknown seeder names are a 404.
 - A `SeedPart` receives `{ tenant }` and works against the in-process `seedTenant` and the HTTP tenant alike.
 - Already have a custom server entry (mail transport, KMS, boot seeds, ...) that also runs in prod?
   Point `serverEntry` at it instead of duplicating `e2e/server.ts`, and mount the seed routes only
@@ -61,6 +70,12 @@ test("member sees the note", async ({ seedTenant, page }) => {
 
 ## Screenshots (`./e2e`)
 
+Seeded identities are unique per run (`admin-<tenantId>@…`). To show a presentable address instead, the
+flow registers the mapping once the tenant exists, and the runner replaces it in text and form values
+right before every capture (again after each theme and viewport change); the seeded data stays as it is:
+`presentIdentities([{ from: tenant.admin.email, to: "anna@example.com" }])` from the scenario fixtures, or
+`captureScreenshot(page, name, { presentIdentities: [...] })` inline.
+
 `runScreenshots`/`runMatrix` register their tests on the same `test` as above, so a scenario's `flow`
 receives the seeded-tenant fixture too:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.313.0",
+  "version": "0.315.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -63,9 +63,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.313.0",
-    "@cosmicdrift/kumiko-dev-server": "0.313.0",
-    "@cosmicdrift/kumiko-framework": "0.313.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.315.0",
+    "@cosmicdrift/kumiko-dev-server": "0.315.0",
+    "@cosmicdrift/kumiko-framework": "0.315.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/changes.json

@@ -1,4 +1,29 @@
 [
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "Screenshot runner replaces generated seed identities with presentable values",
+    "detail": "Seeded identities are unique per run (admin-<tenantId>@…), so screenshots\nshowed a different address on every run. A scenario flow now calls\n`presentIdentities([{ from: tenant.admin.email, to: \"anna@example.com\" }])`\nfrom its fixtures, and runScreenshots/runMatrix replace `from` with `to` in\nthe page's text nodes and input/textarea values right before every capture,\nagain after each theme and viewport change. captureScreenshot takes the same\nlist as `opts.presentIdentities`. Only the rendered page changes: the seeded\ndata, the seed routes and the app UI stay untouched. Code that builds a\n`ScenarioFixtures` object itself (instead of receiving it in a flow) now has\nto pass `presentIdentities` too."
+  },
+  {
+    "version": "0.314.0",
+    "type": "fix",
+    "title": "captureScreenshot, runScreenshots and runMatrix settle after a reload or cross-document navigation",
+    "detail": "Chromium drops the old document's fetch/XHR requests on a reload, goto or\nlocation change without firing requestfinished or requestfailed. The\nin-flight tracker kept those requests forever, so a flow that reloaded\nwhile a data request was still open failed with \"page never settled\".\nThe tracker now clears its in-flight set when the main frame commits a new\ndocument (a main-frame navigation request followed by framenavigated).\nA same-document navigation (pushState) still waits for its requests, and\na navigation that never commits (204, download) keeps them too."
+  },
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "Seed routes seed a SystemAdmin and run app-owned seeders",
+    "detail": "SystemAdmin is now one of the built-in seedable roles. This reverses the\nearlier \"SystemAdmin is never seedable\" rule: the seed gate\n(KUMIKO_TEST_SEED=1, never under NODE_ENV=production, per-run token) is now\nthe only boundary around the seed routes. `tenant.addUser([\"SystemAdmin\"])`\n(seed-user route and in-process seedTenant alike) stores SystemAdmin as a\nglobal user role, never as a membership role; without a tenant role the user\njoins the tenant as Member so the login has a membership.\n`createE2eSeedRoutes({ extraRoles: [\"SystemAdmin\"] })` no longer throws.\n`createE2eSeedRoutes({ extraSeeders: { name: (ctx, tenantId, body) => … } })`\nmounts POST /__test/seed behind the same gate; the flow calls\n`tenant.seed(name, body)` on the seedTenant fixture. Only tenants seeded by\nthat server's seed-tenant route are accepted (403 otherwise), unknown names\nare a 404, `body` arrives as `unknown` and a ZodError from the seeder becomes\na 400. `ctx.write`/`ctx.query` run as the tenant's system user (SystemAdmin)\nand are bound to that tenant, so the target handler must admit SystemAdmin;\nthere is no raw DB access."
+  },
+  {
+    "version": "0.314.0",
+    "type": "breaking",
+    "title": "seed-user only reaches a tenant this server's seed-tenant route created",
+    "detail": "seed-user looked the tenant up via tenant:query:me and only rejected a tenant\nid that did not exist at all, so a tenant seeded by another server or\nin-process without this route's seed-tenant still got a user added. seed-user\nnow checks the same seededTenantIds set as /__test/seed and rejects any other\ntenant with the same 403.",
+    "migration": "Create the tenant via `seedTenant()` (the seed-tenant route) before adding users with `tenant.addUser`."
+  },
   {
     "version": "0.311.0",
     "type": "breaking",

package/src/e2e/constants.ts

@@ -42,6 +42,7 @@ export const SEED_ROUTES = {
   seedTenant: `${SEED_ROUTE_PREFIX}/seed-tenant`,
   seedUser: `${SEED_ROUTE_PREFIX}/seed-user`,
   inbox: `${SEED_ROUTE_PREFIX}/inbox`,
+  extraSeed: `${SEED_ROUTE_PREFIX}/seed`,
 } as const;
 
 // Desktop default for e2e runs and screenshots alike. Playwright's "Desktop

package/src/e2e/index.ts

@@ -47,6 +47,7 @@ export {
   type FlatOptions,
   findIdenticalThemeScreenshots,
   type MatrixOptions,
+  type PresentIdentity,
   runMatrix,
   runScreenshots,
   type Scenario,

package/src/e2e/screenshots.ts

@@ -32,11 +32,22 @@ export async function applyDefaultTheme(page: Page, theme: DefaultThemeId): Prom
   }, theme);
 }
 
+// Seeded identities are unique per run (admin-<tenantId>@…), so a screenshot
+// would show a different address every time. Replaced in the page's text and
+// form values right before each capture; the seeded data stays untouched.
+export interface PresentIdentity {
+  readonly from: string;
+  readonly to: string;
+}
+
 export interface ScenarioFixtures {
   readonly seedTenant: SeedTenantFixture;
   // runMatrix's current locale, for apps whose routes carry the locale in the
   // path (kumiko:locale alone can't change the URL). Undefined in runScreenshots.
   readonly locale?: string;
+  // Called from the flow once the identities exist; applies to every capture
+  // of the scenario, re-applied after each theme and viewport change.
+  readonly presentIdentities: (mappings: readonly PresentIdentity[]) => void;
 }
 
 export interface Scenario {
@@ -68,16 +79,41 @@ export interface Scenario {
 const DATA_REQUEST_TYPES: ReadonlySet<string> = new Set(["fetch", "xhr"]);
 const STABLE_POLLS = 2;
 
+function isMainFrameNavigationRequest(page: Page, request: Request): boolean {
+  if (!request.isNavigationRequest() || request.serviceWorker() !== null) return false;
+  try {
+    return request.frame() === page.mainFrame();
+  } catch {
+    return false;
+  }
+}
+
+// Chromium drops the old document's fetches on a cross-document navigation
+// (reload, goto, location.href) without requestfinished or requestfailed, so
+// they would stay in flight forever. framenavigated alone can't tell that commit
+// apart from a pushState, which must keep them: only a framenavigated preceded by
+// a main-frame navigation request is a new document.
 function countInFlightDataRequests(page: Page): () => number {
   const inFlight = new Set<Request>();
-  const settle = (request: Request): void => {
-    inFlight.delete(request);
-  };
+  let pendingDocumentNavigation: Request | undefined;
   page.on("request", (request) => {
     if (DATA_REQUEST_TYPES.has(request.resourceType())) inFlight.add(request);
+    else if (isMainFrameNavigationRequest(page, request)) pendingDocumentNavigation = request;
+  });
+  page.on("framenavigated", (frame) => {
+    if (frame === page.mainFrame() && pendingDocumentNavigation !== undefined) {
+      pendingDocumentNavigation = undefined;
+      inFlight.clear();
+    }
+  });
+  page.on("requestfinished", (request) => {
+    inFlight.delete(request);
+  });
+  page.on("requestfailed", (request) => {
+    inFlight.delete(request);
+    // A navigation that never commits (204, download) leaves the old document alive.
+    if (request === pendingDocumentNavigation) pendingDocumentNavigation = undefined;
   });
-  page.on("requestfinished", settle);
-  page.on("requestfailed", settle);
   return () => inFlight.size;
 }
 
@@ -112,6 +148,51 @@ async function waitForSettledPage(page: Page, inFlightDataRequests: () => number
     .toBeGreaterThanOrEqual(STABLE_POLLS);
 }
 
+function assertPresentableMappings(mappings: readonly PresentIdentity[]): void {
+  for (const { from } of mappings) {
+    if (from === "") throw new Error("presentIdentities: `from` must not be empty");
+  }
+}
+
+// Runs in the browser, so it may not reference module scope.
+function replaceIdentitiesInDocument(mappings: readonly PresentIdentity[]): void {
+  const present = (text: string): string =>
+    mappings.reduce((current, { from, to }) => current.replaceAll(from, to), text);
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    const text = node.nodeValue ?? "";
+    const presented = present(text);
+    if (presented !== text) node.nodeValue = presented;
+  }
+  for (const field of document.querySelectorAll("input, textarea")) {
+    if (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement) {
+      const presented = present(field.value);
+      if (presented !== field.value) field.value = presented;
+    }
+  }
+}
+
+async function presentIdentitiesOnPage(
+  page: Page,
+  mappings: readonly PresentIdentity[],
+): Promise<void> {
+  if (mappings.length > 0) await page.evaluate(replaceIdentitiesInDocument, mappings);
+}
+
+function collectPresentIdentities(): {
+  readonly mappings: readonly PresentIdentity[];
+  readonly register: (mappings: readonly PresentIdentity[]) => void;
+} {
+  const collected: PresentIdentity[] = [];
+  return {
+    mappings: collected,
+    register: (mappings) => {
+      assertPresentableMappings(mappings);
+      collected.push(...mappings);
+    },
+  };
+}
+
 async function openScenario(
   page: Page,
   s: Scenario,
@@ -179,9 +260,14 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
           await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
           if (opts.pinLocale) await pinEnglishLocale(page);
           const inFlightDataRequests = countInFlightDataRequests(page);
+          const identities = collectPresentIdentities();
           if (s.viewport) await page.setViewportSize(s.viewport);
-          await openScenario(page, s, inFlightDataRequests, { seedTenant });
+          await openScenario(page, s, inFlightDataRequests, {
+            seedTenant,
+            presentIdentities: identities.register,
+          });
           if (s.beforeCapture) await s.beforeCapture(page);
+          await presentIdentitiesOnPage(page, identities.mappings);
           const path = `${outDir}/${s.name}.png`;
           await page.screenshot({
             path,
@@ -400,7 +486,12 @@ export function runMatrix<T extends string>(
             localStorage.removeItem("kumiko:theme");
           }, locale);
           const inFlightDataRequests = countInFlightDataRequests(page);
-          await openScenario(page, s, inFlightDataRequests, { seedTenant, locale });
+          const identities = collectPresentIdentities();
+          await openScenario(page, s, inFlightDataRequests, {
+            seedTenant,
+            locale,
+            presentIdentities: identities.register,
+          });
 
           const digests: ThemeScreenshotDigest<T>[] = [];
           const projectBaseDir =
@@ -412,6 +503,7 @@ export function runMatrix<T extends string>(
               if (plan.mode === "desktop") await page.setViewportSize(VIEWPORTS[vp]);
               await waitForSettledPage(page, inFlightDataRequests);
               if (s.beforeCapture) await s.beforeCapture(page);
+              await presentIdentitiesOnPage(page, identities.mappings);
               const dir = `${projectBaseDir}/${s.name}/${locale}/${theme}`;
               mkdirSync(dir, { recursive: true });
               const path = `${dir}/${vp}.png`;
@@ -470,6 +562,7 @@ export type CaptureFit = "viewport" | "fullPage" | "content";
 export interface CaptureScreenshotOptions {
   readonly reducedMotion?: ReducedMotionOption;
   readonly fit?: CaptureFit;
+  readonly presentIdentities?: readonly PresentIdentity[];
 }
 
 const CONTENT_FIT_MAX_ROUNDS = 4;
@@ -530,21 +623,31 @@ export async function captureScreenshot(
   // skip: a plain e2e run without SCREENSHOT_DIR must not write screenshots.
   if (dir === undefined || dir === "") return;
   const fit = opts.fit ?? "viewport";
+  const identities = opts.presentIdentities ?? [];
+  assertPresentableMappings(identities);
   await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
   await waitForSettledPage(page, inFlightTrackerFor(page));
   const path = `${dir}/${name}.png`;
   mkdirSync(dirname(path), { recursive: true });
-  if (fit === "content") await captureGrownToContent(page, name, path);
+  // Before the content fit too: a presented value of another length can change the overflow.
+  await presentIdentitiesOnPage(page, identities);
+  if (fit === "content") await captureGrownToContent(page, name, path, identities);
   else await page.screenshot({ path, animations: "disabled", fullPage: fit === "fullPage" });
 }
 
-async function captureGrownToContent(page: Page, name: string, path: string): Promise<void> {
+async function captureGrownToContent(
+  page: Page,
+  name: string,
+  path: string,
+  identities: readonly PresentIdentity[],
+): Promise<void> {
   const viewport = page.viewportSize();
   if (viewport === null) {
     throw new Error(`captureScreenshot(${name}): fit "content" needs a page with a viewport`);
   }
   try {
     await growViewportToContent(page, name, viewport.width);
+    await presentIdentitiesOnPage(page, identities);
     await page.screenshot({ path, animations: "disabled" });
   } finally {
     // Later assertions in the same test must run against the original window.

package/src/e2e/seed-contract.ts

@@ -1,7 +1,10 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import * as z from "zod";
 
-export const SEEDABLE_ROLES = [ROLES.TenantAdmin, ROLES.Member] as const;
+// SystemAdmin is seedable: the seed gate (KUMIKO_TEST_SEED=1, never
+// under NODE_ENV=production, per-run token) is the only boundary around these
+// routes. It lands as a global user role, never as a membership role.
+export const SEEDABLE_ROLES = [ROLES.TenantAdmin, ROLES.Member, ROLES.SystemAdmin] as const;
 export const MAX_SEED_MEMBERS = 10;
 export const MAX_TENANT_NAME_LENGTH = 100;
 const MAX_EMAIL_LENGTH = 320;
@@ -34,10 +37,6 @@ export const seedTenantResponseSchema = z.object({
   members: z.array(seededCredentialsSchema),
 });
 
-function isSystemAdminRole(role: string): boolean {
-  return role.trim().toLowerCase() === ROLES.SystemAdmin.toLowerCase();
-}
-
 export function resolveSeedableRoles(extraRoles: readonly string[] = []): readonly string[] {
   for (const role of extraRoles) {
     if (typeof role !== "string" || role.trim() === "") {
@@ -45,11 +44,6 @@ export function resolveSeedableRoles(extraRoles: readonly string[] = []): readon
         `createE2eSeedRoutes: extraRoles entries must be non-empty strings, got ${JSON.stringify(role)}`,
       );
     }
-    if (isSystemAdminRole(role)) {
-      throw new Error(
-        `createE2eSeedRoutes: extraRoles must not contain ${ROLES.SystemAdmin}; it is never seedable`,
-      );
-    }
   }
   return [...new Set<string>([...SEEDABLE_ROLES, ...extraRoles])];
 }
@@ -73,6 +67,16 @@ export const seedUserRequestSchema = createSeedUserRequestSchema();
 
 export const seedUserResponseSchema = seededCredentialsSchema;
 
+const MAX_SEEDER_NAME_LENGTH = 100;
+
+export const extraSeedRequestSchema = z.strictObject({
+  tenantId: z.uuid(),
+  seeder: z.string().min(1).max(MAX_SEEDER_NAME_LENGTH),
+  body: z.unknown().optional(),
+});
+
+export const extraSeedResponseSchema = z.object({ result: z.unknown() });
+
 export const inboxQuerySchema = z.strictObject({
   tenantId: z.uuid().optional(),
   to: z.string().min(1).max(MAX_EMAIL_LENGTH),
@@ -92,3 +96,4 @@ export const inboxResponseSchema = z.object({ messages: z.array(capturedMailSche
 export type CapturedMail = z.infer<typeof capturedMailSchema>;
 export type SeedTenantResponse = z.infer<typeof seedTenantResponseSchema>;
 export type SeedUserRequest = z.infer<typeof seedUserRequestSchema>;
+export type ExtraSeedRequest = z.infer<typeof extraSeedRequestSchema>;

package/src/e2e/seed-route.ts

@@ -4,24 +4,26 @@ import {
   getInbox,
   mailTransportInMemoryFeature,
 } from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
-import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import {
   type ExtraRouteDefinition,
   ExtraRouteRejection,
   type SignatureExtraRouteVerifyRequest,
   signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
-import type * as z from "zod";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
 import {
   persistTenantRows,
   persistUserRows,
   type SeedWriter,
   unwrapSavedRow,
+  unwrapWriteData,
 } from "../seed-tenant";
 import { SEED_ENABLE_ENV, SEED_ROUTES, SEED_TOKEN_ENV, SEED_TOKEN_HEADER } from "./constants";
 import {
   type CapturedMail,
   createSeedUserRequestSchema,
+  extraSeedRequestSchema,
   inboxQuerySchema,
   seedTenantRequestSchema,
 } from "./seed-contract";
@@ -30,13 +32,16 @@ type ParsedBody<T> =
   | { readonly success: true; readonly data: T }
   | { readonly success: false; readonly error: string };
 
+function formatIssues(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`)
+    .join("; ");
+}
+
 function parseWith<S extends z.ZodType>(schema: S, value: unknown): ParsedBody<z.infer<S>> {
   const result = schema.safeParse(value);
   if (result.success) return { success: true, data: result.data };
-  const error = result.error.issues
-    .map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`)
-    .join("; ");
-  return { success: false, error };
+  return { success: false, error: formatIssues(result.error) };
 }
 
 function parseJsonBody<S extends z.ZodType>(schema: S, raw: string): ParsedBody<z.infer<S>> {
@@ -89,8 +94,44 @@ function assertGateOpen(request: SignatureExtraRouteVerifyRequest): void {
   }
 }
 
+// Shared by seed-user and extra-seed: both address a tenant by id, and a
+// tenant exists in seededTenantIds by construction only after this same
+// server's seed-tenant route created it.
+function assertSeededTenant(tenantId: string, seededTenantIds: ReadonlySet<string>): void {
+  if (!seededTenantIds.has(tenantId)) {
+    throw new ExtraRouteRejection(403, {
+      error: `tenant ${tenantId} was not seeded by this server's seed-tenant route`,
+    });
+  }
+}
+
+// Every call runs with system privileges inside the one seeded tenant the
+// route verified; there is no way to address another tenant through it.
+export type E2eSeederContext = {
+  readonly write: (handlerQn: string, payload: unknown) => Promise<unknown>;
+  readonly query: (handlerQn: string, payload: unknown) => Promise<unknown>;
+};
+
+// `body` is whatever the client sent; validate it with a zod schema's parse(),
+// a ZodError becomes a 400. The return value goes back as JSON `{ result }`.
+export type E2eExtraSeeder = (
+  ctx: E2eSeederContext,
+  tenantId: TenantId,
+  body: unknown,
+) => Promise<unknown>;
+
+type VerifiedExtraSeed = {
+  readonly seederName: string;
+  readonly seeder: E2eExtraSeeder;
+  readonly tenantId: TenantId;
+  readonly body: unknown;
+};
+
 export type E2eSeedRoutesOptions = {
   readonly extraRoles?: readonly string[];
+  // Reachable only through tenant.seed(name, body) and only for tenants the
+  // seed-tenant route of this same server seeded.
+  readonly extraSeeders?: Readonly<Record<string, E2eExtraSeeder>>;
   // Apps that send tenantless mail (signup/forgot-password/magic-link) via
   // their own raw createInMemoryTransport() pass its `sent` array here so
   // the inbox route can read it without a tenantId. Independent of
@@ -120,6 +161,11 @@ export function createE2eSeedRoutes(
   options: E2eSeedRoutesOptions = {},
 ): readonly ExtraRouteDefinition[] {
   const seedUserRequestSchema = createSeedUserRequestSchema(options.extraRoles);
+  const extraSeeders = options.extraSeeders ?? {};
+  // In-memory on purpose: the seed token is known to every test client, so
+  // only server-side state can tell a tenant this server seeded from any
+  // other tenant id a client might send.
+  const seededTenantIds = new Set<string>();
 
   const seedTenantRoute = signatureRoute<z.infer<typeof seedTenantRequestSchema>>({
     method: "POST",
@@ -133,13 +179,13 @@ export function createE2eSeedRoutes(
       const write: SeedWriter = async (handlerQn, payload, tenantId) =>
         unwrapSavedRow(handlerQn, await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }));
       try {
-        return c.json(
-          await persistTenantRows(write, {
-            name: verified.name,
-            users: verified.members,
-            admin: verified.admin,
-          }),
-        );
+        const persisted = await persistTenantRows(write, {
+          name: verified.name,
+          users: verified.members,
+          admin: verified.admin,
+        });
+        seededTenantIds.add(persisted.id);
+        return c.json(persisted);
       } catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "seed failed" }, 500);
       }
@@ -152,20 +198,11 @@ export function createE2eSeedRoutes(
     entry: "signature",
     verify: async (request) => {
       assertGateOpen(request);
-      return parseOrReject(parseJsonBody(seedUserRequestSchema, request.rawBody));
+      const parsed = parseOrReject(parseJsonBody(seedUserRequestSchema, request.rawBody));
+      assertSeededTenant(parsed.tenantId, seededTenantIds);
+      return parsed;
     },
     handler: async (c, verified, deps) => {
-      // No raw db in signature-route deps (fw#3050) — tenant:query:me, run as
-      // a SystemAdmin scoped to verified.tenantId, is the existing
-      // fetchOne(tenantTable, {id: tenantId}) lookup, just behind the dispatcher.
-      const tenantRow = await deps.dispatchSystemQuery({
-        handlerQn: TenantQueries.me,
-        payload: {},
-        tenantId: verified.tenantId,
-      });
-      if (tenantRow === null) {
-        return c.json({ error: `unknown tenant ${verified.tenantId}` }, 404);
-      }
       const write: SeedWriter = async (handlerQn, payload, tenantId) =>
         unwrapSavedRow(handlerQn, await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }));
       try {
@@ -225,5 +262,51 @@ export function createE2eSeedRoutes(
     },
   });
 
-  return [seedTenantRoute, seedUserRoute, inboxRoute];
+  const extraSeedRoute = signatureRoute<VerifiedExtraSeed>({
+    method: "POST",
+    path: SEED_ROUTES.extraSeed,
+    entry: "signature",
+    verify: async (request) => {
+      assertGateOpen(request);
+      const parsed = parseOrReject(parseJsonBody(extraSeedRequestSchema, request.rawBody));
+      const seeder = Object.hasOwn(extraSeeders, parsed.seeder)
+        ? extraSeeders[parsed.seeder]
+        : undefined;
+      if (seeder === undefined) {
+        const registered = Object.keys(extraSeeders).join(", ") || "none";
+        throw new ExtraRouteRejection(404, {
+          error: `unknown seeder "${parsed.seeder}"; registered: ${registered}`,
+        });
+      }
+      assertSeededTenant(parsed.tenantId, seededTenantIds);
+      return {
+        seederName: parsed.seeder,
+        seeder,
+        tenantId: parsed.tenantId,
+        body: parsed.body,
+      };
+    },
+    handler: async (c, verified, deps) => {
+      const { tenantId } = verified;
+      const seederContext: E2eSeederContext = {
+        write: async (handlerQn, payload) =>
+          unwrapWriteData(
+            handlerQn,
+            await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }),
+          ),
+        query: (handlerQn, payload) => deps.dispatchSystemQuery({ handlerQn, payload, tenantId }),
+      };
+      try {
+        const result = await verified.seeder(seederContext, tenantId, verified.body);
+        return c.json({ result: result ?? null });
+      } catch (error) {
+        if (error instanceof z.ZodError) {
+          return c.json({ error: `seeder "${verified.seederName}": ${formatIssues(error)}` }, 400);
+        }
+        return c.json({ error: error instanceof Error ? error.message : "seed failed" }, 500);
+      }
+    },
+  });
+
+  return [seedTenantRoute, seedUserRoute, inboxRoute, extraSeedRoute];
 }

package/src/e2e/seeded-tenant-fixture.ts

@@ -20,6 +20,8 @@ import { clearSession, createHttpApi, loginViaApi } from "./auth-kit";
 import { SEED_ROUTES } from "./constants";
 import { seedRouteHeaders } from "./mail-capture";
 import {
+  type ExtraSeedRequest,
+  extraSeedResponseSchema,
   type SeedUserRequest,
   seedTenantResponseSchema,
   seedUserResponseSchema,
@@ -29,6 +31,9 @@ export type E2eSeedTenantOptions = Omit<SeedTenantOptions, "persist">;
 
 export type E2eSeededTenant = SeededTenant & {
   readonly loginAs: (page: Page, user: SeededUser) => Promise<void>;
+  // Runs an app seeder registered via createE2eSeedRoutes({ extraSeeders })
+  // inside this tenant and resolves to its JSON result, unvalidated.
+  readonly seed: (seeder: string, body?: unknown) => Promise<unknown>;
 };
 
 export type SeedTenantFixture = (opts?: E2eSeedTenantOptions) => Promise<E2eSeededTenant>;
@@ -133,6 +138,15 @@ export async function provideSeedTenant(
       api: httpApiFor(admin),
       apiAs: httpApiFor,
       loginAs,
+      seed: async (seeder, body) =>
+        (
+          await postSeedRoute(
+            request,
+            SEED_ROUTES.extraSeed,
+            { tenantId, seeder, body } satisfies ExtraSeedRequest,
+            extraSeedResponseSchema,
+          )
+        ).result,
     };
 
     for (const part of opts.with ?? []) await part({ tenant });

package/src/seed-tenant.ts

@@ -17,6 +17,7 @@ import {
   type SeededCredentials,
   type SeededTenant,
   type SeedTenantOptions,
+  splitSeedRoles,
   withSession,
 } from "./seed-types";
 
@@ -81,14 +82,19 @@ function isSavedRow(value: unknown): value is SavedRow {
   return isPlainObject(data) && typeof data["version"] === "number";
 }
 
-export function unwrapSavedRow(handlerQn: string, result: WriteResult): SavedRow {
+export function unwrapWriteData(handlerQn: string, result: WriteResult): unknown {
   if (!result.isSuccess) {
     throw new Error(`seedTenant: ${handlerQn} failed: ${JSON.stringify(result.error)}`);
   }
-  if (!isSavedRow(result.data)) {
+  return result.data;
+}
+
+export function unwrapSavedRow(handlerQn: string, result: WriteResult): SavedRow {
+  const data = unwrapWriteData(handlerQn, result);
+  if (!isSavedRow(data)) {
     throw new Error(`seedTenant: ${handlerQn} returned no saved row`);
   }
-  return result.data;
+  return data;
 }
 
 export function stackSeedWriter(stack: TestStack): SeedWriter {
@@ -112,12 +118,14 @@ export async function persistUserRows(
   const light = lightCredentials(
     identity.email !== undefined ? substituteTenantId(identity.email, tenantId) : undefined,
   );
+  const { globalRoles, membershipRoles } = splitSeedRoles(roles);
   const created = await write(
     UserHandlers.create,
     {
       email: light.email,
       passwordHash: await hashPassword(light.password),
       displayName: identity.displayName ?? `Seed ${light.id.slice(0, 8)}`,
+      ...(globalRoles.length > 0 ? { roles: [...globalRoles] } : {}),
     },
     tenantId,
   );
@@ -126,7 +134,11 @@ export async function persistUserRows(
     { id: created.id, version: created.data.version, changes: { emailVerified: true } },
     tenantId,
   );
-  await write(TenantHandlers.addMember, { userId: created.id, tenantId, roles }, tenantId);
+  await write(
+    TenantHandlers.addMember,
+    { userId: created.id, tenantId, roles: membershipRoles },
+    tenantId,
+  );
   return { id: created.id, email: light.email, password: light.password };
 }
 

package/src/seed-types.ts

@@ -1,3 +1,4 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
 
@@ -49,10 +50,30 @@ export type SeededTenant = {
   readonly apiAs: (user: SeededUser) => BoundApi;
 };
 
+export type SeedRoleSplit = {
+  readonly globalRoles: readonly string[];
+  readonly membershipRoles: readonly string[];
+};
+
+// SystemAdmin only counts as a global user role (login strips it from
+// membership roles), yet login still needs a membership: a SystemAdmin
+// without a tenant role therefore also joins the tenant as Member.
+export function splitSeedRoles(roles: readonly string[]): SeedRoleSplit {
+  const globalRoles = roles.filter((role) => role === ROLES.SystemAdmin);
+  const tenantRoles = roles.filter((role) => role !== ROLES.SystemAdmin);
+  const membershipRoles =
+    globalRoles.length > 0 && tenantRoles.length === 0 ? [ROLES.Member] : tenantRoles;
+  return { globalRoles, membershipRoles };
+}
+
 export function withSession(
   credentials: SeededCredentials,
   tenantId: TenantId,
   roles: readonly string[],
 ): SeededUser {
-  return { ...credentials, session: { id: credentials.id, tenantId, roles } };
+  const { globalRoles, membershipRoles } = splitSeedRoles(roles);
+  return {
+    ...credentials,
+    session: { id: credentials.id, tenantId, roles: [...globalRoles, ...membershipRoles] },
+  };
 }