@cosmicdrift/kumiko-bundled-features 0.295.0 → 0.296.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.295.0",
+  "version": "0.296.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>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.295.0",
-    "@cosmicdrift/kumiko-framework": "0.295.0",
-    "@cosmicdrift/kumiko-headless": "0.295.0",
-    "@cosmicdrift/kumiko-renderer": "0.295.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.295.0",
-    "@cosmicdrift/kumiko-types": "0.295.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.296.0",
+    "@cosmicdrift/kumiko-framework": "0.296.0",
+    "@cosmicdrift/kumiko-headless": "0.296.0",
+    "@cosmicdrift/kumiko-renderer": "0.296.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.296.0",
+    "@cosmicdrift/kumiko-types": "0.296.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.295.0",
-    "@cosmicdrift/kumiko-locale-es": "0.295.0",
+    "@cosmicdrift/kumiko-locale-de": "0.296.0",
+    "@cosmicdrift/kumiko-locale-es": "0.296.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/audit/__tests__/audit-screens.boot.test.ts

@@ -27,9 +27,10 @@ describe("audit log screen + handler access alignment", () => {
   });
 
   test("the user:user actor reference makes `user` a hard boot dependency (fw#3103)", () => {
+    // fw#3108's refEntity check now catches the missing "user" feature before the "requires" check does.
     expect(() =>
       validateBoot([createConfigFeature(), createTenantFeature(), createAuditFeature()]),
-    ).toThrow(/requires feature "user"/);
+    ).toThrow(/refEntity\) targets entity "user:user".*Known entities in feature "user": \(none\)/);
   });
 
   test("audit-log screen is declarative, access.admin-gated", () => {

package/src/audit/feature.ts

@@ -59,8 +59,6 @@ export function createAuditFeature(): FeatureDefinition {
           {
             field: "createdBy",
             label: i18nKey("audit.log.col.actor"),
-            // Resolves only for SystemAdmin until fw#3107: the lookup QN this
-            // derives, user:query:user:list, is SystemAdmin-only.
             refEntity: "user:user",
             refLabelField: "displayName",
           },

package/src/delivery/__tests__/delivery-log-query.integration.test.ts

@@ -11,6 +11,8 @@ import {
   testTenantId,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant/feature";
 import { DeliveryQueries } from "../constants";
 import { createDeliveryFeature } from "../feature";
 import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
@@ -31,7 +33,9 @@ const admin = createTestUser({ id: 701, roles: ["TenantAdmin"], tenantId });
 const systemAdmin = createTestUser({ id: 709, roles: ["SystemAdmin"], tenantId });
 
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [createDeliveryFeature()] });
+  stack = await setupTestStack({
+    features: [createConfigFeature(), createTenantFeature(), createDeliveryFeature()],
+  });
   await unsafePushTables(stack.db, { deliveryAttemptsTable, notificationPreferencesTable });
   await insertMany(stack.db, deliveryAttemptsTable, [
     {

package/src/delivery/__tests__/delivery-screens.boot.test.ts

@@ -1,11 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import { access, isOpenToAllGranted, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant/feature";
 import { DELIVERY_LOG_SCREEN_ID } from "../constants";
 import { createDeliveryFeature } from "../feature";
 
 describe("delivery screens + handler access alignment", () => {
-  const features = [createDeliveryFeature()];
+  const features = [createConfigFeature(), createTenantFeature(), createDeliveryFeature()];
 
   test("boot-validates with delivery-log screen registered", () => {
     expect(() => validateBoot(features)).not.toThrow();
@@ -38,7 +40,11 @@ describe("delivery screens + handler access alignment", () => {
 
   test("boot-validates with a narrowed access option", () => {
     expect(() =>
-      validateBoot([createDeliveryFeature({ access: access.systemAdmin })]),
+      validateBoot([
+        createConfigFeature(),
+        createTenantFeature(),
+        createDeliveryFeature({ access: access.systemAdmin }),
+      ]),
     ).not.toThrow();
   });
 });

package/src/delivery/__tests__/delivery-security.integration.test.ts

@@ -9,6 +9,8 @@ import {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant/feature";
 import { DELIVERY_LOG_SCREEN_ID, DeliveryHandlers, DeliveryQueries } from "../constants";
 import { createDeliveryFeature } from "../feature";
 import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
@@ -17,7 +19,7 @@ let stack: TestStack;
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [createDeliveryFeature()],
+    features: [createConfigFeature(), createTenantFeature(), createDeliveryFeature()],
   });
   await unsafePushTables(stack.db, { deliveryAttemptsTable, notificationPreferencesTable });
 });
@@ -28,7 +30,11 @@ afterAll(async () => {
 
 describe("delivery access matrix", () => {
   test("delivery log handler and screen share access.admin", () => {
-    const registry = createRegistry([createDeliveryFeature()]);
+    const registry = createRegistry([
+      createConfigFeature(),
+      createTenantFeature(),
+      createDeliveryFeature(),
+    ]);
     expect(rolesOf(registry.getQueryHandler(DeliveryQueries.log)?.access)).toEqual([
       ...access.admin,
     ]);

package/src/delivery/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.296.0",
+    "type": "breaking",
+    "title": "delivery requires tenant",
+    "migration": "delivery now declares r.requires(\"tenant\") because its delivery-log screen references tenant:tenant. Stacks that mount delivery must also mount createTenantFeature() (and its config dependency)."
+  },
   {
     "version": "0.271.0",
     "type": "improvement",

package/src/delivery/feature.ts

@@ -47,6 +47,8 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
       recommended: true,
     });
     r.systemScope();
+    // delivery-log's tenantId column has refEntity: "tenant:tenant" (boot-checked).
+    r.requires("tenant");
     // Backing table: the (tenant,user,type,channel) uniqueIndex lives only on
     // the physical table, not on the entity fields, so the generator would
     // otherwise omit it → duplicate preference rows on concurrent upserts.

package/src/tenant/__tests__/member-directory.integration.test.ts

@@ -0,0 +1,179 @@
+// tenant:query:member-directory backs every `user:user` reference label
+// (fw#3107). It replaced the SystemAdmin-only user:query:user:list as lookup
+// source, so the invariants that matter: a TenantAdmin reaches it, sees only
+// their own tenant and gets no more than id + display name, while a SystemAdmin
+// keeps the global reach the roster gave them.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetPiiSubjectKmsForTests, resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { REFERENCE_LOOKUP_SOURCES } from "@cosmicdrift/kumiko-framework/ui-types";
+import { createConfigFeature } from "../../config";
+import { configValuesTable } from "../../config/table";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { seedUser } from "../../user/seeding";
+import { TenantQueries } from "../constants";
+import { createTenantFeature } from "../feature";
+import { tenantMembershipsTable } from "../membership-table";
+import { tenantEntity } from "../schema/tenant";
+import { seedTenant, seedTenantMembership } from "../seeding";
+
+const ownTenantId = testTenantId(1);
+const foreignTenantId = testTenantId(2);
+
+type DirectoryRow = Readonly<Record<string, unknown>>;
+
+let stack: TestStack;
+
+function tenantAdmin(userId: string): SessionUser {
+  return { id: userId, tenantId: ownTenantId, roles: ["TenantAdmin"] };
+}
+
+async function seedMember(
+  tenantId: string,
+  displayName: string,
+  roles: readonly string[],
+): Promise<string> {
+  const { id } = await seedUser(stack.db, {
+    email: `${displayName.toLowerCase().replace(/\s+/g, "-")}@example.com`,
+    displayName,
+    emailVerified: true,
+  });
+  await seedTenantMembership(stack.db, { userId: id, tenantId, roles: [...roles] });
+  return id;
+}
+
+async function queryDirectory(caller: SessionUser): Promise<readonly DirectoryRow[]> {
+  const result = await stack.http.queryOk<{ rows: readonly DirectoryRow[] }>(
+    TenantQueries.memberDirectory,
+    {},
+    caller,
+  );
+  return result.rows;
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), createUserFeature(), createTenantFeature()],
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+beforeEach(async () => {
+  await resetTestTables(stack.db, [userTable, tenantMembershipsTable]);
+  await seedTenant(stack.db, { id: ownTenantId, key: "directory-own", name: "Own Tenant" });
+  await seedTenant(stack.db, {
+    id: foreignTenantId,
+    key: "directory-foreign",
+    name: "Foreign Tenant",
+  });
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("tenant:query:member-directory (fw#3107)", () => {
+  test("is the lookup source the renderer uses for user:user references", () => {
+    expect(REFERENCE_LOOKUP_SOURCES["user:user"]).toEqual({
+      queryQn: TenantQueries.memberDirectory,
+      labelKey: "label",
+    });
+  });
+
+  test("a TenantAdmin gets their own members as id/label, never a foreign-tenant user", async () => {
+    const adminId = await seedMember(ownTenantId, "Own Admin", ["TenantAdmin"]);
+    const colleagueId = await seedMember(ownTenantId, "Own Colleague", ["User"]);
+    const foreignId = await seedMember(foreignTenantId, "Foreign Person", ["TenantAdmin"]);
+
+    const rows = await queryDirectory(tenantAdmin(adminId));
+
+    const byId = new Map(rows.map((row) => [String(row["id"]), row]));
+    expect(byId.get(adminId)?.["label"]).toBe("Own Admin");
+    expect(byId.get(colleagueId)?.["label"]).toBe("Own Colleague");
+    expect(byId.has(foreignId)).toBe(false);
+    expect(rows.length).toBe(2);
+  });
+
+  test("rows carry only id and label — no email or roles leave the directory", async () => {
+    const adminId = await seedMember(ownTenantId, "Own Admin", ["TenantAdmin"]);
+
+    const rows = await queryDirectory(tenantAdmin(adminId));
+
+    expect(rows.map((row) => Object.keys(row).sort())).toEqual([["id", "label"]]);
+  });
+
+  test("a user shared with a foreign tenant is still listed once, under the display name", async () => {
+    const adminId = await seedMember(ownTenantId, "Own Admin", ["TenantAdmin"]);
+    const sharedId = await seedMember(foreignTenantId, "Shared Person", ["User"]);
+    await seedTenantMembership(stack.db, {
+      userId: sharedId,
+      tenantId: ownTenantId,
+      roles: ["User"],
+    });
+
+    const rows = await queryDirectory(tenantAdmin(adminId));
+
+    expect(rows.filter((row) => row["id"] === sharedId)).toEqual([
+      { id: sharedId, label: "Shared Person" },
+    ]);
+  });
+
+  test("display names come back decrypted when a PII-subject KMS is active", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const adminId = await seedMember(ownTenantId, "Encrypted Admin", ["TenantAdmin"]);
+
+    const rows = await queryDirectory(tenantAdmin(adminId));
+
+    expect(rows).toEqual([{ id: adminId, label: "Encrypted Admin" }]);
+  });
+
+  test("a SystemAdmin without membership in the active tenant still resolves every user, themselves included", async () => {
+    const memberId = await seedMember(ownTenantId, "Own Colleague", ["User"]);
+    const foreignId = await seedMember(foreignTenantId, "Foreign Person", ["User"]);
+    const { id: operatorId } = await seedUser(stack.db, {
+      email: "operator@example.com",
+      displayName: "Platform Operator",
+      emailVerified: true,
+    });
+
+    const rows = await queryDirectory({
+      id: operatorId,
+      tenantId: ownTenantId,
+      roles: ["SystemAdmin"],
+    });
+
+    const labelById = new Map(rows.map((row) => [String(row["id"]), row["label"]]));
+    expect(labelById.get(operatorId)).toBe("Platform Operator");
+    expect(labelById.get(memberId)).toBe("Own Colleague");
+    expect(labelById.get(foreignId)).toBe("Foreign Person");
+  });
+
+  test("a plain member without an admin role is refused", async () => {
+    await seedMember(ownTenantId, "Own Admin", ["TenantAdmin"]);
+    const memberId = await seedMember(ownTenantId, "Plain Member", ["User"]);
+
+    const res = await stack.http.query(
+      TenantQueries.memberDirectory,
+      {},
+      { id: memberId, tenantId: ownTenantId, roles: ["User"] },
+    );
+
+    expect(res.status).toBe(403);
+  });
+});

package/src/tenant/__tests__/tenant-directory.integration.test.ts

@@ -0,0 +1,124 @@
+// tenant:query:tenant-directory backs every `tenant:tenant` reference label
+// (fw#3142). It replaced the SystemAdmin-only tenant:query:tenant:list as
+// lookup source, so the invariants that matter: a TenantAdmin reaches it and
+// sees only their own tenant, while a SystemAdmin keeps the global reach the
+// entity-convention list gave them.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { REFERENCE_LOOKUP_SOURCES } from "@cosmicdrift/kumiko-framework/ui-types";
+import { createConfigFeature } from "../../config";
+import { configValuesTable } from "../../config/table";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { seedUser } from "../../user/seeding";
+import { TenantQueries } from "../constants";
+import { createTenantFeature } from "../feature";
+import { tenantEntity } from "../schema/tenant";
+import { seedTenant } from "../seeding";
+
+const ownTenantId = testTenantId(1);
+const foreignTenantId = testTenantId(2);
+
+type DirectoryRow = Readonly<Record<string, unknown>>;
+
+let stack: TestStack;
+
+function tenantAdmin(userId: string): SessionUser {
+  return { id: userId, tenantId: ownTenantId, roles: ["TenantAdmin"] };
+}
+
+async function queryDirectory(caller: SessionUser): Promise<readonly DirectoryRow[]> {
+  const result = await stack.http.queryOk<{ rows: readonly DirectoryRow[] }>(
+    TenantQueries.tenantDirectory,
+    {},
+    caller,
+  );
+  return result.rows;
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), createUserFeature(), createTenantFeature()],
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+beforeEach(async () => {
+  await resetTestTables(stack.db, [userTable]);
+  await seedTenant(stack.db, { id: ownTenantId, key: "directory-own", name: "Own Tenant" });
+  await seedTenant(stack.db, {
+    id: foreignTenantId,
+    key: "directory-foreign",
+    name: "Foreign Tenant",
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("tenant:query:tenant-directory (fw#3142)", () => {
+  test("is the lookup source the renderer uses for tenant:tenant references", () => {
+    expect(REFERENCE_LOOKUP_SOURCES["tenant:tenant"]).toEqual({
+      queryQn: TenantQueries.tenantDirectory,
+      labelKey: "label",
+    });
+  });
+
+  test("a TenantAdmin gets only their own tenant as id/label", async () => {
+    const { id: adminId } = await seedUser(stack.db, {
+      email: "own-admin@example.com",
+      displayName: "Own Admin",
+      emailVerified: true,
+    });
+
+    const rows = await queryDirectory(tenantAdmin(adminId));
+
+    expect(rows).toEqual([{ id: ownTenantId, label: "Own Tenant" }]);
+  });
+
+  test("a SystemAdmin without membership in the active tenant still resolves every tenant", async () => {
+    const { id: operatorId } = await seedUser(stack.db, {
+      email: "operator@example.com",
+      displayName: "Platform Operator",
+      emailVerified: true,
+    });
+
+    const rows = await queryDirectory({
+      id: operatorId,
+      tenantId: ownTenantId,
+      roles: ["SystemAdmin"],
+    });
+
+    const labelById = new Map(rows.map((row) => [String(row["id"]), row["label"]]));
+    expect(labelById.get(ownTenantId)).toBe("Own Tenant");
+    expect(labelById.get(foreignTenantId)).toBe("Foreign Tenant");
+  });
+
+  test("a plain member without an admin role is refused", async () => {
+    const { id: memberId } = await seedUser(stack.db, {
+      email: "plain-member@example.com",
+      displayName: "Plain Member",
+      emailVerified: true,
+    });
+
+    const res = await stack.http.query(
+      TenantQueries.tenantDirectory,
+      {},
+      { id: memberId, tenantId: ownTenantId, roles: ["User"] },
+    );
+
+    expect(res.status).toBe(403);
+  });
+});

package/src/tenant/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.296.0",
+    "type": "improvement",
+    "title": "Tenant reference columns show display names for TenantAdmins (fw#3142)",
+    "detail": "Every `tenant:tenant` reference (the delivery-log tenantId column, `LIST_ROW_META_REFERENCES.tenantId`, and any screen that references a tenant) resolved its label through the entity-convention query `tenant:query:tenant:list`. That handler is a SystemAdmin-only entity-list handler, so a TenantAdmin got a 403 and every cell fell back to the raw UUID.\nThe entity-convention handler stays SystemAdmin-only. Instead the new `tenant:query:tenant-directory` (`access.admin`) returns just `{ id, label }` pairs: an admin gets their own tenant, a SystemAdmin keeps the global reach of `tenant:query:tenant:list`. The query is not exposed to agents. The central `REFERENCE_LOOKUP_SOURCES` map in `@cosmicdrift/kumiko-framework/ui-types` now routes `tenant:tenant` lookups there, the same way it already routes `user:user` lookups to the member directory (fw#3107).",
+    "migration": "No code change needed. A `tenant:tenant` reference picker or column in an edit form or list now shows a non-SystemAdmin their own tenant's name instead of failing with a 403 and falling back to the raw id. Set `optionsQuery` on the reference field if a screen needs a different source."
+  },
+  {
+    "version": "0.296.0",
+    "type": "improvement",
+    "title": "User reference columns show display names for TenantAdmins (fw#3107)",
+    "detail": "Every `user:user` reference (the audit-log actor, the sessions user column, their detail screens) resolved its label through the entity-convention query `user:query:user:list`. That handler is the SystemAdmin cross-tenant user roster, so a TenantAdmin got a 403 and every cell fell back to the raw UUID — in practice every tenant admin reading their own audit log.\nThe roster stays SystemAdmin-only: its `tenants` column joins every membership of a user and would expose foreign tenant names. Instead the new `tenant:query:member-directory` (`access.admin`) returns just `{ id, label }` pairs — the display name, no email, no roles. An admin gets their own tenant's members; a SystemAdmin keeps the global reach the roster gave them, so operator actions in tenants they are no member of still resolve. The query is not exposed to agents. The new central `REFERENCE_LOOKUP_SOURCES` map in `@cosmicdrift/kumiko-framework/ui-types` routes `user:user` lookups there, the same way `SYSTEM_REFERENCE_LABELS` already applies per referenced entity. The list lookup, the read-only detail value, the reference combobox and embedded-list reference cells all consult it; a reference field's own `optionsQuery` still wins.",
+    "migration": "No code change needed. Two behavior shifts to be aware of: for a non-SystemAdmin, a `user:user` reference picker in an edit form now offers the active tenant's members (it used to fail with a 403 and stay empty) — set `optionsQuery` on the reference field if a screen needs a different source. And a `user:user` label now only resolves when the `tenant` feature is mounted. In an app that mounts `sessions` without `tenant`, a SystemAdmin — who used to see names there — now sees the raw id, the same fallback a TenantAdmin got before; mount `createTenantFeature()` to get names back."
+  },
   {
     "version": "0.271.0",
     "type": "improvement",
@@ -15,31 +29,31 @@
     "version": "0.209.0",
     "type": "improvement",
     "title": "tenant: single /members screen replaces the members-card/pending-card split (#2223)",
-    "detail": "New `tenant:query:team:list` handler merges active memberships and pending invitations into one projectionList screen (`membersScreen`), with a `status` facet, sortable/searchable columns, and a danger-styled `cancel-invitation` row action visible only on pending rows. `createTenantFeature({ inviteScreen: true })` additionally wires a drawer-hosted invite actionForm onto the toolbar (bound to auth-email-password's `invite-create` handler) \u2014 off by default, and only safe to enable once the app also configures `createAuthEmailPasswordFeature({ invite: {...} })`, since the boot validator rejects the actionForm's cross-feature handler QN otherwise. The old `members`/`invitations` query handlers and their custom `MembersScreen` component are unaffected and stay registered for existing callers; `updateMemberRoles` stays SystemAdmin-only and off this screen."
+    "detail": "New `tenant:query:team:list` handler merges active memberships and pending invitations into one projectionList screen (`membersScreen`), with a `status` facet, sortable/searchable columns, and a danger-styled `cancel-invitation` row action visible only on pending rows. `createTenantFeature({ inviteScreen: true })` additionally wires a drawer-hosted invite actionForm onto the toolbar (bound to auth-email-password's `invite-create` handler) — off by default, and only safe to enable once the app also configures `createAuthEmailPasswordFeature({ invite: {...} })`, since the boot validator rejects the actionForm's cross-feature handler QN otherwise. The old `members`/`invitations` query handlers and their custom `MembersScreen` component are unaffected and stay registered for existing callers; `updateMemberRoles` stays SystemAdmin-only and off this screen."
   },
   {
     "version": "0.165.0",
     "type": "fix",
     "title": "resolveRawDb: removed redundant null check",
-    "detail": "CodeQL flagged db !== null after if (!db) \u2014 truthiness already excludes null. Internal cleanup, no API break."
+    "detail": "CodeQL flagged db !== null after if (!db) — truthiness already excludes null. Internal cleanup, no API break."
   },
   {
     "version": "0.165.0",
     "type": "fix",
     "title": "Seed hook: explicit SessionUser typing",
-    "detail": "Fixed tenant seeding type annotation \u2014 prevents implicit any propagation in seed handlers."
+    "detail": "Fixed tenant seeding type annotation — prevents implicit any propagation in seed handlers."
   },
   {
     "version": "0.165.0",
     "type": "fix",
     "title": "Seed afterCommit + real tenant rescope",
-    "detail": "ScheduleAfterCommit now available on HandlerContext \u2014 fireEntityPostSave queues after TX commit instead of mid-transaction. DB/notify/hasFeature/_tenantId are correctly rescoped when targeting an entity's tenant.",
-    "migration": "Only affects custom seed handlers using fireEntityPostSave \u2014 now afterCommit-compatible."
+    "detail": "ScheduleAfterCommit now available on HandlerContext — fireEntityPostSave queues after TX commit instead of mid-transaction. DB/notify/hasFeature/_tenantId are correctly rescoped when targeting an entity's tenant.",
+    "migration": "Only affects custom seed handlers using fireEntityPostSave — now afterCommit-compatible."
   },
   {
     "version": "0.163.0",
     "type": "improvement",
     "title": "tenant: seedTenant fires entity postSave hooks (#1463).",
-    "detail": "tenant: seedTenant fires entity postSave hooks (#1463). `seedTenant` writes through the raw event-store executor, which never fired postSave hooks \u2014 self-signup (`provisionSignupAccount` \u2192 `signup-confirm`) silently skipped feature-registered entity hooks like tier-engine's auto-default-tier and app-level auto-default-compliance, leaving new tenants without a tier/compliance row. `seedTenant` and `provisionSignupAccount` take a new optional `hooks: { registry, context }` param; passing it fires the same entity-scoped postSave hooks the dispatcher would, without the full dispatch roundtrip. Existing call-sites are unaffected \u2014 the param is optional and append-only."
+    "detail": "tenant: seedTenant fires entity postSave hooks (#1463). `seedTenant` writes through the raw event-store executor, which never fired postSave hooks — self-signup (`provisionSignupAccount` → `signup-confirm`) silently skipped feature-registered entity hooks like tier-engine's auto-default-tier and app-level auto-default-compliance, leaving new tenants without a tier/compliance row. `seedTenant` and `provisionSignupAccount` take a new optional `hooks: { registry, context }` param; passing it fires the same entity-scoped postSave hooks the dispatcher would, without the full dispatch roundtrip. Existing call-sites are unaffected — the param is optional and append-only."
   }
 ]

package/src/tenant/constants.ts

@@ -49,6 +49,12 @@ export const TenantQueries = {
   list: "tenant:query:list",
   memberships: "tenant:query:memberships",
   members: "tenant:query:members",
+  // Label source for `user:user` reference columns — see
+  // REFERENCE_LOOKUP_SOURCES in the framework's ui-types.
+  memberDirectory: "tenant:query:member-directory",
+  // Label source for `tenant:tenant` reference columns — see
+  // REFERENCE_LOOKUP_SOURCES in the framework's ui-types.
+  tenantDirectory: "tenant:query:tenant-directory",
   activeTenantIds: "tenant:query:active-tenant-ids",
   resolveUserIds: "tenant:query:resolve-user-ids",
   // Pending Invitations für den aktuellen Tenant (Admin-UI-Liste).

package/src/tenant/feature.ts

@@ -16,11 +16,13 @@ import { createWrite } from "./handlers/create.write";
 import { invitationsQuery } from "./handlers/invitations.query";
 import { listQuery } from "./handlers/list.query";
 import { meQuery } from "./handlers/me.query";
+import { memberDirectoryQuery } from "./handlers/member-directory.query";
 import { membersQuery } from "./handlers/members.query";
 import { membershipsQuery } from "./handlers/memberships.query";
 import { removeMemberWrite } from "./handlers/remove-member.write";
 import { resolveUserIdsQuery } from "./handlers/resolve-user-ids.query";
 import { teamListQuery } from "./handlers/team-list.query";
+import { tenantDirectoryQuery } from "./handlers/tenant-directory.query";
 import { disableWrite, enableWrite } from "./handlers/toggle-enabled.write";
 import { updateWrite } from "./handlers/update.write";
 import { updateMemberRolesWrite } from "./handlers/update-member-roles.write";
@@ -132,6 +134,8 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
       list: r.queryHandler(listQuery),
       memberships: r.queryHandler(membershipsQuery),
       members: r.queryHandler(membersQuery),
+      memberDirectory: r.queryHandler(memberDirectoryQuery),
+      tenantDirectory: r.queryHandler(tenantDirectoryQuery),
       activeTenantIds: r.queryHandler(activeTenantIdsQuery),
       resolveUserIds: r.queryHandler(resolveUserIdsQuery),
       invitations: r.queryHandler(invitationsQuery),

package/src/tenant/handlers/is-system-admin.ts

@@ -0,0 +1,5 @@
+import { access, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+
+export function isSystemAdmin(user: Pick<SessionUser, "roles">): boolean {
+  return access.systemAdmin.some((role) => user.roles.includes(role));
+}

package/src/tenant/handlers/member-directory.query.ts

@@ -0,0 +1,74 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  definePagedQueryHandler,
+  MAX_LIST_LIMIT,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { decryptStoredPii, mapWithConcurrency } from "../../shared";
+import { userTable } from "../../user";
+import { tenantMembershipsTable } from "../membership-table";
+import { isSystemAdmin } from "./is-system-admin";
+
+// Shares the KMS adapter's small dedicated pool, same rationale as
+// members.query.ts.
+const KMS_POOL_CONCURRENCY = 4;
+
+async function loadMemberUserIds(db: TenantDb, tenantId: string): Promise<readonly string[]> {
+  const memberships = await selectMany(db, tenantMembershipsTable, { tenantId });
+  return [...new Set(memberships.map((row) => String(row["userId"])))];
+}
+
+// Label source behind every `user:user` reference column (fw#3107). The
+// entity-convention lookup, user:query:user:list, is a SystemAdmin
+// cross-tenant roster, so a TenantAdmin got a 403 and every actor cell fell
+// back to the raw UUID. Deliberately narrower than tenant:query:members:
+// id + display name only, no email, so the screens that only need a name
+// never decrypt an address.
+//
+// A SystemAdmin keeps the global scope the roster gave them: operators act in
+// tenants they are no member of, and their own audit entries and sessions must
+// still resolve. A TenantAdmin only ever sees their own tenant's members.
+// ponytail: capped at `limit` (200 list lookup, 50 combobox) like every
+// reference lookup; beyond that the cell falls back to the raw id.
+export const memberDirectoryQuery = definePagedQueryHandler({
+  name: "memberDirectory",
+  schema: z.object({
+    limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(MAX_LIST_LIMIT),
+  }),
+  access: { roles: access.admin },
+  description:
+    "Lists users as id/label pairs for resolving user references to display names: the caller's own tenant members for an admin, every user for a SystemAdmin; carries no email or role data.",
+  agent: { expose: false },
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:member-directory requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const { limit } = query.payload;
+    let users: readonly { id: unknown; displayName?: unknown }[];
+    if (isSystemAdmin(query.user)) {
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "SystemAdmin reference labels span every tenant, as user:query:user:list did",
+      );
+      users = await selectMany(db, userTable, undefined, { limit });
+    } else {
+      const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+      const userIds = (await loadMemberUserIds(db, query.user.tenantId)).slice(0, limit);
+      users = userIds.length > 0 ? await selectMany(db, userTable, { id: [...userIds] }) : [];
+    }
+    const rows = await mapWithConcurrency(users, KMS_POOL_CONCURRENCY, async (user) => {
+      const id = String(user.id);
+      const label =
+        typeof user.displayName === "string"
+          ? await decryptStoredPii(user.displayName, "displayName", "tenant:member-directory")
+          : null;
+      return { id, label: label ?? id };
+    });
+    return { rows, nextCursor: null };
+  },
+});