@cosmicdrift/kumiko-bundled-features 0.216.0 → 0.217.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.216.0",
+  "version": "0.217.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.216.0",
-    "@cosmicdrift/kumiko-framework": "0.216.0",
-    "@cosmicdrift/kumiko-headless": "0.216.0",
-    "@cosmicdrift/kumiko-renderer": "0.216.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.216.0",
-    "@cosmicdrift/kumiko-types": "0.216.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.217.0",
+    "@cosmicdrift/kumiko-framework": "0.217.0",
+    "@cosmicdrift/kumiko-headless": "0.217.0",
+    "@cosmicdrift/kumiko-renderer": "0.217.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.217.0",
+    "@cosmicdrift/kumiko-types": "0.217.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -160,7 +160,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.216.0",
-    "@cosmicdrift/kumiko-locale-es": "0.216.0"
+    "@cosmicdrift/kumiko-locale-de": "0.217.0",
+    "@cosmicdrift/kumiko-locale-es": "0.217.0"
   }
 }

package/src/auth-email-password/__tests__/multi-roles.integration.test.ts

@@ -91,7 +91,7 @@ async function seedUser(
       displayName: email.split("@")[0] ?? "user",
       // user.roles im create wird privileged geprüft — systemAdmin hat
       // SystemAdmin-Rolle (siehe TestUsers.systemAdmin).
-      roles: JSON.stringify(globalRoles),
+      roles: globalRoles,
     },
     systemAdmin,
   );
@@ -132,7 +132,7 @@ describe("multi-roles: login mergt globale + membership-roles", () => {
     // nur Zufall (z.B. wenn login-handler hardcoded SystemAdmin reinpacken
     // würde). Direct DB-read schließt das aus.
     const dbRow = await selectMany(stack.db, userTable, { id: userId });
-    expect(dbRow[0]?.roles).toBe(JSON.stringify(["SystemAdmin"]));
+    expect(dbRow[0]?.roles).toEqual(["SystemAdmin"]);
 
     const { user } = await login("syadmin@example.com", "pw-long-enough");
     expect(user.tenantId).toBe(tenantA);

package/src/auth-email-password/web/__tests__/auth-client.test.ts

@@ -520,7 +520,7 @@ describe("fetchCurrentUser", () => {
     expect(res?.globalRoles).toEqual([]);
   });
 
-  test("mixed-type array roles → empty globalRoles", async () => {
+  test("mixed-type JSON roles → keeps string entries only", async () => {
     globalThis.fetch = mock(async () =>
       jsonResponse({
         data: { id: "u1", email: "a@b.c", displayName: "User", roles: '["Admin",1,true]' },
@@ -529,7 +529,19 @@ describe("fetchCurrentUser", () => {
 
     const res = await fetchCurrentUser();
 
-    expect(res?.globalRoles).toEqual([]);
+    expect(res?.globalRoles).toEqual(["Admin"]);
+  });
+
+  test("native array roles (jsonb wire) → globalRoles", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({
+        data: { id: "u1", email: "a@b.c", displayName: "User", roles: ["SystemAdmin"] },
+      }),
+    ) as unknown as typeof fetch;
+
+    const res = await fetchCurrentUser();
+
+    expect(res?.globalRoles).toEqual(["SystemAdmin"]);
   });
 
   test("non-ok status → throws", async () => {

package/src/auth-email-password/web/auth-client.ts

@@ -10,6 +10,7 @@
 // nicht divergieren.
 
 import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-live";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 
 export type TenantSummary = {
   readonly tenantId: string;
@@ -414,19 +415,8 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
   };
 }
 
-// Defensive parse — server-side ist die Spalte JSON-encoded string[],
-// aber bei migration-drift oder corrupted-row liefern wir [] statt einen
-// runtime-throw der die ganze SessionProvider-mount blockt.
-function parseGlobalRoles(raw: string | undefined): readonly string[] {
-  if (typeof raw !== "string" || raw.length === 0) return [];
-  try {
-    // @cast-boundary user-row.roles is JSON-encoded string[] per server contract
-    const parsed = JSON.parse(raw) as unknown;
-    if (Array.isArray(parsed) && parsed.every((r) => typeof r === "string")) {
-      return parsed;
-    }
-  } catch {
-    // malformed JSON → behave as empty
-  }
-  return [];
+// Defensive parse — roles may be jsonb string[] (0.217+) or a legacy
+// JSON-encoded string; malformed → [] so SessionProvider mount never throws.
+function parseGlobalRoles(raw: unknown): readonly string[] {
+  return parseRoles(raw);
 }

package/src/user/__tests__/admin-screens.boot.test.ts

@@ -32,6 +32,28 @@ describe("user + tenant SystemAdmin admin screens", () => {
     expect(user.screens["user-edit"]?.type).toBe("entityEdit");
   });
 
+  test("user-edit layout includes roles (multiSelect) so SystemAdmin can promote peers", () => {
+    const user = createUserFeature();
+    const edit = user.screens["user-edit"];
+    expect(edit?.type).toBe("entityEdit");
+    if (edit?.type !== "entityEdit") throw new Error("expected entityEdit");
+    const fieldNames = edit.layout.sections.flatMap((s) =>
+      "fields" in s ? s.fields.map((f) => (typeof f === "string" ? f : f.field)) : [],
+    );
+    expect(fieldNames).toContain("roles");
+    expect(user.entities?.["user"]?.fields["roles"]?.type).toBe("multiSelect");
+  });
+
+  test("user-list columns include roles and tenants for the platform roster", () => {
+    const user = createUserFeature();
+    const list = user.screens["user-list"];
+    expect(list?.type).toBe("entityList");
+    if (list?.type !== "entityList") throw new Error("expected entityList");
+    const cols = list.columns.map((c) => (typeof c === "string" ? c : c.field));
+    expect(cols).toEqual(expect.arrayContaining(["roles", "tenants", "email"]));
+    expect(user.entities?.["user"]?.derivedFields?.["tenants"]).toBeDefined();
+  });
+
   test("user list/detail/create/update handlers already sit on the screen QNs", () => {
     const user = createUserFeature();
     // → user:query:user:list, user:query:user:detail

package/src/user/__tests__/user.integration.test.ts

@@ -14,6 +14,7 @@ import {
   resetTestTables,
   updateRows,
 } from "@cosmicdrift/kumiko-framework/testing";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { UserErrors, UserHandlers, UserQueries } from "../constants";
 import { createUserFeature } from "../feature";
 import { userEntity, userTable } from "../schema/user";
@@ -41,7 +42,7 @@ async function seedUser(overrides: {
   email: string;
   displayName: string;
   passwordHash?: string;
-  roles?: string;
+  roles?: readonly string[];
 }): Promise<{ id: string }> {
   const res = await stack.http.writeOk<{ id: string }>(
     UserHandlers.create,
@@ -390,7 +391,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: created.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       systemAdmin,
     );
@@ -400,7 +401,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       { id: created.id },
       systemAdmin,
     );
-    expect(JSON.parse(String(reloaded["roles"] ?? "[]"))).toEqual(["SystemAdmin"]);
+    expect(parseRoles(reloaded["roles"])).toEqual(["SystemAdmin"]);
   });
 
   test("promoted user with SystemAdmin role can perform SystemAdmin-only queries", async () => {
@@ -419,7 +420,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: created.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       systemAdmin,
     );
@@ -446,7 +447,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: created.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["User", "Editor"]) },
+        changes: { roles: ["User", "Editor"] },
       },
       systemAdmin,
     );
@@ -456,7 +457,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       { id: created.id },
       systemAdmin,
     );
-    expect(JSON.parse(String(reloaded["roles"] ?? "[]"))).toEqual(["User", "Editor"]);
+    expect(parseRoles(reloaded["roles"])).toEqual(["User", "Editor"]);
   });
 
   test("TenantAdmin gets 403 on global role mutation (HTTP level check)", async () => {
@@ -473,7 +474,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: target.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       tenantAdmin,
     );
@@ -501,7 +502,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: tenantAdmin.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       actor,
     );
@@ -523,7 +524,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: user.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       normalUser,
     );
@@ -547,7 +548,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: target.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       attacker,
     );
@@ -570,7 +571,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         id: target.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["SuperPowerUnknown"]) },
+        changes: { roles: ["SuperPowerUnknown"] },
       },
       systemAdmin,
     );
@@ -587,7 +588,7 @@ describe("scenario 5: global roles mutation & elevation guard (#2388)", () => {
       {
         email: "unknown-role-create@example.com",
         displayName: "BadRole",
-        roles: JSON.stringify(["UnknownRole"]),
+        roles: ["UnknownRole"],
       },
       systemAdmin,
     );
@@ -604,7 +605,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
     const onlyAdmin = await seedUser({
       email: "only-admin@example.com",
       displayName: "OnlyAdmin",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
     const loaded = await stack.http.queryOk<Record<string, unknown>>(
       UserQueries.detail,
@@ -618,7 +619,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
       {
         id: onlyAdmin.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["User"]) },
+        changes: { roles: ["User"] },
       },
       systemAdmin,
     );
@@ -632,7 +633,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
     const secondAdmin = await seedUser({
       email: "second-admin@example.com",
       displayName: "SecondAdmin",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
 
     // Demoting onlyAdmin now succeeds (since secondAdmin remains active)
@@ -641,7 +642,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
       {
         id: onlyAdmin.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["User"]) },
+        changes: { roles: ["User"] },
       },
       systemAdmin,
     );
@@ -657,7 +658,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
       {
         id: secondAdmin.id,
         version: secondLoaded["version"],
-        changes: { roles: JSON.stringify(["User"]) },
+        changes: { roles: ["User"] },
       },
       systemAdmin,
     );
@@ -674,7 +675,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
     const onlyAdmin = await seedUser({
       email: "empty-roles-admin@example.com",
       displayName: "EmptyRolesAdmin",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
     const loaded = await stack.http.queryOk<Record<string, unknown>>(
       UserQueries.detail,
@@ -687,7 +688,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
       {
         id: onlyAdmin.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify([]) },
+        changes: { roles: [] },
       },
       systemAdmin,
     );
@@ -702,7 +703,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
     const onlyAdmin = await seedUser({
       email: "non-role-admin@example.com",
       displayName: "InitialAdminName",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
     const loaded = await stack.http.queryOk<Record<string, unknown>>(
       UserQueries.detail,
@@ -733,14 +734,14 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
     await seedUser({
       email: "the-system-admin@example.com",
       displayName: "TheAdmin",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
 
     // Seed a normal user
     const normalUser = await seedUser({
       email: "regular-user@example.com",
       displayName: "RegularUser",
-      roles: JSON.stringify(["User"]),
+      roles: ["User"],
     });
     const loaded = await stack.http.queryOk<Record<string, unknown>>(
       UserQueries.detail,
@@ -754,7 +755,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
       {
         id: normalUser.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["User", "Editor"]) },
+        changes: { roles: ["User", "Editor"] },
       },
       systemAdmin,
     );
@@ -764,19 +765,19 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
       { id: normalUser.id },
       systemAdmin,
     );
-    expect(JSON.parse(String(reloaded["roles"] ?? "[]"))).toEqual(["User", "Editor"]);
+    expect(parseRoles(reloaded["roles"])).toEqual(["User", "Editor"]);
   });
 
   test("concurrent demotions of the last two SystemAdmins: one wins, one gets 409", async () => {
     const adminA = await seedUser({
       email: "race-admin-a@example.com",
       displayName: "Race Admin A",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
     const adminB = await seedUser({
       email: "race-admin-b@example.com",
       displayName: "Race Admin B",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
 
     const loadedA = await stack.http.queryOk<Record<string, unknown>>(
@@ -796,7 +797,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
         {
           id: adminA.id,
           version: loadedA["version"],
-          changes: { roles: JSON.stringify(["User"]) },
+          changes: { roles: ["User"] },
         },
         systemAdmin,
       ),
@@ -805,7 +806,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
         {
           id: adminB.id,
           version: loadedB["version"],
-          changes: { roles: JSON.stringify(["User"]) },
+          changes: { roles: ["User"] },
         },
         systemAdmin,
       ),
@@ -843,7 +844,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
           { id },
           systemAdmin,
         );
-        return JSON.parse(String(row["roles"] ?? "[]")).includes("SystemAdmin");
+        return parseRoles(row["roles"]).includes("SystemAdmin");
       }),
     );
     expect(stillAdmin.filter(Boolean)).toHaveLength(1);
@@ -853,12 +854,12 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
     const activeAdmin = await seedUser({
       email: "active-admin@example.com",
       displayName: "ActiveAdmin",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
     const softDeletedAdmin = await seedUser({
       email: "deleted-admin@example.com",
       displayName: "DeletedAdmin",
-      roles: JSON.stringify(["SystemAdmin"]),
+      roles: ["SystemAdmin"],
     });
 
     // Soft-delete the second admin directly
@@ -875,7 +876,7 @@ describe("scenario 6: last active SystemAdmin protection (#2388)", () => {
       {
         id: activeAdmin.id,
         version: loaded["version"],
-        changes: { roles: JSON.stringify(["User"]) },
+        changes: { roles: ["User"] },
       },
       systemAdmin,
     );

package/src/user/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.217.0",
+    "type": "improvement",
+    "title": "user-list: roles multiSelect + tenants column; roles editable as SystemAdmin (fw#2384 follow-up)",
+    "detail": "user.roles is now createMultiSelectField (jsonb string[], options=[SystemAdmin]) so entityEdit shows a real multi-select instead of a raw JSON text box — SystemAdmins can promote another SystemAdmin from the UI. user-list columns gain roles + tenants; tenants is a derived field filled by the list handler from memberships (platform roster was unusable without tenant context). switch-tenant + auth-client parseRoles accept jsonb arrays (string-only deserialize dropped SystemAdmin on tenant switch). Soft-deleted users stay hidden by default.",
+    "migration": "Run `kumiko-schema generate` and apply — migrates read_users.roles from text to jsonb USING roles::jsonb. Existing JSON array strings (`[]`, `[\"SystemAdmin\"]`) convert cleanly. Consumers that wrote roles as a JSON-encoded string via user:create/update should pass string[] instead (parseRoles still accepts both on read)."
+  },
   {
     "version": "0.167.1",
     "type": "breaking",

package/src/user/constants.ts

@@ -2,6 +2,11 @@
 // Feature name
 export const USER_FEATURE = "user" as const;
 
+/** Assignable global (cross-tenant) roles on user.roles — SystemAdmin is the
+ *  platform operator. Membership roles (TenantAdmin/Admin/User/…) live on
+ *  tenant-membership, not here. */
+export const GLOBAL_ROLE_OPTIONS = ["SystemAdmin"] as const;
+
 // Qualified write handler names. Handlers carry the "user:" entity prefix so
 // field-level access rules (passwordHash system-only etc.) are wired up.
 export const UserHandlers = {

package/src/user/handlers/create.write.ts

@@ -39,11 +39,10 @@ export const createWrite = defineWriteHandler({
     displayName: z.string().min(1).max(100),
     locale: z.string().min(2).max(10).optional(),
     timezone: z.string().max(64).refine(isValidIanaTimeZone, "invalid IANA time zone").optional(),
-    // Global roles — JSON-encoded string[]. Optional because the entity default
-    // is "[]"; set when bootstrapping privileged global roles. Field-level
-    // write access (privileged) is defense-in-depth — create is already
-    // system/SystemAdmin-only.
-    roles: z.string().optional(),
+    // Global roles — multiSelect jsonb string[]. Optional (entity default []).
+    // Field-level write access (privileged) is defense-in-depth — create is
+    // already system/SystemAdmin-only.
+    roles: z.union([z.string(), z.array(z.string())]).optional(),
   }),
   access: { roles: ["system", "SystemAdmin"] },
   handler: async (event, ctx) => {
@@ -81,7 +80,7 @@ export const createWrite = defineWriteHandler({
           }),
         );
       }
-      createPayload = { ...event.payload, roles: JSON.stringify(newRoles) };
+      createPayload = { ...event.payload, roles: newRoles };
     }
 
     const result = await crud.create(createPayload, event.user, db);

package/src/user/handlers/list.query.ts

@@ -1,8 +1,120 @@
-import { access, defineEntityListHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  defineEntityListHandler,
+  type HandlerContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+// kumiko-lint-ignore cross-feature-import SystemAdmin user-list joins memberships for tenants column
+import { tenantMembershipsTable, tenantTable } from "../../tenant";
 import { userEntity } from "../schema/user";
 
-// System-wide user listing is SystemAdmin-only. Tenant admins list their
-// members via the tenant feature (which scopes by membership, not globally).
-export const listQuery = defineEntityListHandler("user", userEntity, {
+const baseList = defineEntityListHandler("user", userEntity, {
   access: { roles: access.systemAdmin },
 });
+
+type MembershipRow = { userId: unknown; tenantId: unknown };
+type TenantRow = { id: unknown; name?: unknown; key?: unknown };
+
+function isMissingRelation(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return msg.includes("does not exist") || msg.includes("42P01");
+}
+
+async function loadMemberships(
+  db: TenantDb,
+  userIds: readonly string[],
+): Promise<readonly MembershipRow[] | null> {
+  try {
+    return await selectMany<MembershipRow>(db, tenantMembershipsTable, {
+      userId: { in: [...userIds] },
+    });
+  } catch (err) {
+    // User-only test stacks (and mid-migration DBs) may lack membership tables.
+    if (isMissingRelation(err)) return null;
+    throw err;
+  }
+}
+
+function tenantLabelById(tenants: readonly TenantRow[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const t of tenants) {
+    const id = String(t.id ?? "");
+    if (id === "") continue;
+    map.set(id, String(t.name ?? t.key ?? id));
+  }
+  return map;
+}
+
+function labelsByUserId(
+  memberships: readonly MembershipRow[],
+  labelByTenantId: Map<string, string>,
+): Map<string, string[]> {
+  const map = new Map<string, string[]>();
+  for (const m of memberships) {
+    const userId = String(m.userId ?? "");
+    const tenantId = String(m.tenantId ?? "");
+    if (userId === "" || tenantId === "") continue;
+    const label = labelByTenantId.get(tenantId) ?? tenantId;
+    const list = map.get(userId) ?? [];
+    list.push(label);
+    map.set(userId, list);
+  }
+  return map;
+}
+
+async function attachTenantLabels(
+  rows: readonly Record<string, unknown>[],
+  db: TenantDb,
+): Promise<Record<string, unknown>[]> {
+  if (rows.length === 0) return [];
+  const userIds = rows.map((r) => String(r["id"] ?? "")).filter((id) => id !== "");
+  if (userIds.length === 0) return [...rows];
+
+  const memberships = await loadMemberships(db, userIds);
+  if (memberships === null) {
+    return rows.map((row) => ({ ...row, tenants: "—" }));
+  }
+
+  const tenantIds = [
+    ...new Set(memberships.map((m) => String(m.tenantId ?? "")).filter((id) => id !== "")),
+  ];
+  const tenants =
+    tenantIds.length > 0
+      ? await selectMany<TenantRow>(db, tenantTable, { id: { in: tenantIds } })
+      : [];
+  const byUser = labelsByUserId(memberships, tenantLabelById(tenants));
+  return rows.map((row) => {
+    const labels = byUser.get(String(row["id"] ?? "")) ?? [];
+    return { ...row, tenants: labels.length > 0 ? labels.join(", ") : "—" };
+  });
+}
+
+function dbForList(ctx: HandlerContext): TenantDb {
+  if (!ctx.systemDb) {
+    throw new Error("user:list requires r.systemScope() / ctx.systemDb");
+  }
+  return ctx.systemDb.acknowledgeCrossTenant(
+    "user identity list is cross-tenant; tenants column joins memberships",
+  );
+}
+
+// System-wide user listing is SystemAdmin-only. Tenant admins list their
+// members via the tenant feature (which scopes by membership, not globally).
+// Wraps the entity-convention list so each row carries a `tenants` label
+// (derived field) — without it the platform roster is unusable for ops.
+export const listQuery = {
+  ...baseList,
+  handler: async (
+    query: Parameters<NonNullable<typeof baseList.handler>>[0],
+    ctx: HandlerContext,
+  ) => {
+    const result = await baseList.handler?.(query, ctx);
+    if (result === null || typeof result !== "object" || !("rows" in result)) {
+      return result;
+    }
+    const envelope = result as { rows: readonly Record<string, unknown>[] };
+    const rows = await attachTenantLabels(envelope.rows, dbForList(ctx));
+    return { ...envelope, rows };
+  },
+};

package/src/user/handlers/update-roles.ts

@@ -52,14 +52,16 @@ function isActiveSystemAdminRow(row: UserRolesRow): boolean {
 
 async function countOtherActiveSystemAdmins(db: TenantDb, excludeUserId: string): Promise<number> {
   const tableName = asEntityTableMeta(userTable)?.tableName ?? "read_users";
-  // kumiko-lint-ignore raw-sql LIKE prefilter for SystemAdmin roster under advisory lock
+  // kumiko-lint-ignore raw-sql jsonb @> prefilter for SystemAdmin roster under advisory lock
   const rows = (await asRawClient(db.raw).unsafe(
     `SELECT id, roles, status, is_deleted AS "isDeleted"
      FROM ${quoteIdent(tableName)}
      WHERE is_deleted = false
        AND (status = $1 OR status IS NULL)
-       AND roles LIKE '%SystemAdmin%'`,
-    [USER_STATUS.Active],
+       AND roles @> $2::jsonb`,
+    // Pass a JS array — JSON.stringify + $n::jsonb double-encodes to a jsonb string
+    // (postgres.js), so `@>` never matches a roles array.
+    [USER_STATUS.Active, ["SystemAdmin"]],
   )) as UserRolesRow[];
   return rows.filter((u) => u.id !== excludeUserId && isActiveSystemAdminRow(u)).length;
 }
@@ -138,7 +140,8 @@ export async function applyUserRolesUpdate(
 
   const normalizedChanges = {
     ...event.payload.changes,
-    roles: JSON.stringify(newRoles),
+    // multiSelect column is jsonb string[] — do not JSON.stringify.
+    roles: newRoles,
   };
 
   // Persist roles first. Session revoke runs only after a successful update so a

package/src/user/i18n.ts

@@ -6,6 +6,8 @@ export const USER_I18N: Readonly<Record<string, LocalizedString>> = {
   "user:entity:user:field:email": { en: "Email" },
   "user:entity:user:field:displayName": { en: "Display name" },
   "user:entity:user:field:roles": { en: "Roles" },
+  "user:entity:user:field:tenants": { en: "Tenants" },
+  "user:entity:user:field:roles:option:SystemAdmin": { en: "SystemAdmin" },
   "user:entity:user:field:status": { en: "Status" },
   "user:entity:user:field:emailVerified": { en: "Email verified" },
   "user:entity:user:field:locale": { en: "Locale" },

package/src/user/schema/user.ts

@@ -2,12 +2,15 @@ import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createBooleanField,
+  createDerivedField,
   createEntity,
+  createMultiSelectField,
   createSelectField,
   createTextField,
   createTimestampField,
   createTzField,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { GLOBAL_ROLE_OPTIONS } from "../constants";
 
 /**
  * User-Lifecycle-Status (S2.U1). Single source of truth — Auth-Middleware
@@ -112,16 +115,13 @@ export const userEntity = createEntity({
       access: { write: access.privileged },
     }),
 
-    // Globale Rollen — parallel zu tenantMemberships.roles. JSON-encoded
-    // string[]; parseRoles() deserialisiert beim Read. Login-Handler mergt
-    // diese Rollen mit den tenant-membership-roles in die Session — so
-    // sind sie tenant-unabhängig (z.B. SystemAdmin, BillingAdmin). Default
-    // "[]" damit die Session-Roles-Merge keinen NULL-Branch braucht.
-    // Schreibrecht privileged: ein User darf sich nicht selbst zum
-    // SystemAdmin machen.
-    roles: createTextField({
-      required: true,
-      default: "[]",
+    // Global (cross-tenant) roles — parallel to tenantMemberships.roles.
+    // multiSelect stores jsonb string[]; login merges these with membership
+    // roles into the session. Write access privileged: users cannot self-elevate
+    // to SystemAdmin. Closed options = only assignable platform roles.
+    roles: createMultiSelectField({
+      options: GLOBAL_ROLE_OPTIONS,
+      default: [],
       access: { write: access.privileged },
     }),
 
@@ -179,6 +179,14 @@ export const userEntity = createEntity({
   // Global (not tenant-scoped): user is a tenant-agnostic identity
   // aggregate (systemStream: true) — a composite (tenantId, email) would
   // leave the same email resolvable twice.
+  // Filled by user:list / user:detail enrichment (membership → tenant names).
+  // derive() is a placeholder — list/detail handlers overwrite after the join.
+  derivedFields: {
+    tenants: createDerivedField({
+      valueType: "text",
+      derive: () => "",
+    }),
+  },
   indexes: [{ columns: ["email"], unique: true, name: "read_users_email_unique" }],
 });
 

package/src/user/screens.ts

@@ -7,12 +7,16 @@ import type {
 // feature runs with `r.systemScope()`, the entityList query returns every
 // user across all tenants — the SystemAdmin platform roster. Both screens are
 // SystemAdmin-gated and stay inert until an app navs them (no auto-nav).
+//
+// `roles` is a multiSelect (global SystemAdmin). `tenants` is a derived field
+// filled by the list handler from memberships — without it the roster is
+// unusable for ops (waitlist signups look like platform users with no context).
 
 export const userListScreen: EntityListScreenDefinition = {
   id: "user-list",
   type: "entityList",
   entity: "user",
-  columns: ["email", "displayName", "status", "emailVerified"],
+  columns: ["email", "displayName", "roles", "tenants", "status", "emailVerified"],
   rowActions: [
     {
       kind: "navigate",

package/src/user/seeding.ts

@@ -33,7 +33,7 @@ export type SeedUserOptions = {
    *  der argon2-Hashing übernimmt. */
   readonly passwordHash?: string;
   readonly locale?: string;
-  /** Globale Rollen — landen in users.roles als JSON-encoded string[].
+  /** Global roles — land in users.roles as jsonb string[].
    *  Werden vom login-handler in die Session-Roles parallel zu tenant-
    *  membership-roles gemerged. Default: leer-array. Typisches Beispiel:
    *  `["SystemAdmin"]` für den Plattform-Operator. */
@@ -101,7 +101,7 @@ export async function seedUser(
       displayName: options.displayName,
       ...(options.passwordHash !== undefined && { passwordHash: options.passwordHash }),
       ...(options.locale !== undefined && { locale: options.locale }),
-      ...(options.roles !== undefined && { roles: JSON.stringify(options.roles) }),
+      ...(options.roles !== undefined && { roles: [...options.roles] }),
       ...(options.emailVerified !== undefined && { emailVerified: options.emailVerified }),
     },
     by,