lael-labs/executor

.changeset/member-directory-readers.md+10−0

@@ -0,0 +1,10 @@
	1	---
	2	"@executor-js/cloud": patch
	3	"@executor-js/api": patch
	4	"@executor-js/react": patch
	5	"@executor-js/sdk": patch
	6	---
	7
	8	Member lists, the admin users page, and seat counts on cloud now read from the local membership mirror through the shared `MemberDirectory` seam instead of fanning out one WorkOS read per member. The admin users page gains an email/name search.
	9
	10	Deploy prerequisite (cloud): `bun run --cwd apps/cloud db:backfill-workos-mirror:prod` must complete before this build is deployed, and its printed membership count should match WorkOS. Until the backfill has stamped the mirror's marker, seat reporting to Autumn is skipped with a warning (never a partial count) and member lists show only members who have signed in since the mirror shipped.

apps/cloud/src/account/account-api.ts+5−3

   AccountProvider,
   makeAccountApiLayer,
   requestScopedMiddleware,
+  type MemberDirectory,
 } from "@executor-js/api/server";
 import { ApiKeyService } from "../auth/api-keys";
 // Builds the WorkOS `AccountProvider` per request, providing it to the handler.
 // Long-lived `WorkOSClient | AutumnService` come from the surrounding context
 // (Autumn provided by `makeAccountApiLive` for the seat-gate); the per-request
-// `UserStoreService` is supplied by the combined `rsLive` layer.
+// `UserStoreService` / `WorkOsMirror` / `MemberDirectory` are supplied by the
+// combined `rsLive` layer.
 // `ApiKeyService.WorkOS` is built here on top of the boot `WorkOSClient`.
 const AccountProviderMiddleware = HttpRouter.middleware<{ provides: AccountProvider }>()(
   Effect.gen(function* () {
  * (the seat-gate) stays a residual requirement, satisfied by the app `boot`.
  */
 export const workosAccountMiddleware = (
-  rsLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror>,
+  rsLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror | MemberDirectory>,
 ) => AccountProviderMiddleware.combine(requestScopedMiddleware(rsLive)).layer;
 export const makeAccountApiLive = (
-  rsLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror>,
+  rsLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror | MemberDirectory>,
 ) => {
   // Cloud builds the WorkOS `AccountProvider` INSIDE the request body (so it
   // closes over the per-request postgres socket), so it can't be a self-

apps/cloud/src/account/org-api-key-revoke.node.test.ts+10−1

 import { describe, expect, it } from "@effect/vitest";
 import { Effect, Layer } from "effect";
-import { AccountProvider } from "@executor-js/api/server";
+import { AccountProvider, MemberDirectory } from "@executor-js/api/server";
 import { AccountError, AccountForbidden } from "@executor-js/api";
 import { ApiKeyService, OrgApiKeyNotFound } from "../auth/api-keys";
   organizationBackfilledAt: () => Effect.die("revoke does not report seats"),
 });
+// Revoke lists no members either.
+const stubDirectory = Layer.succeed(MemberDirectory)({
+  membership: () => Effect.die("revoke does not read the member directory"),
+  members: () => Effect.die("revoke does not read the member directory"),
+  membersById: () => Effect.die("revoke does not read the member directory"),
+  findByEmail: () => Effect.die("revoke does not read the member directory"),
+});
 const stubAutumn = Layer.succeed(AutumnService)({
   use: () => Effect.die("revoke does not touch billing"),
   ensureCustomer: () => Effect.die("revoke does not touch billing"),
             stubWorkOS,
             stubUsers,
             stubMirror,
+            stubDirectory,
             stubApiKeys,
             stubAutumn,
             Layer.succeed(AccountCaller)({ session: session(accountId) }),

apps/cloud/src/account/workos-account-service.ts+66−34

@@ -1,6 +1,6 @@
1	import { Context, Effect, Layer } from "effect";	1	import { Context, Effect, Layer } from "effect";
2		2
3	import { AccountProvider, type AccountHeaders } from "@executor-js/api/server";	3	import { AccountProvider, MemberDirectory, type AccountHeaders } from "@executor-js/api/server";
4	import {	4	import {
5	AccountError,	5	AccountError,
6	AccountForbidden,	6	AccountForbidden,
@@ -12,6 +12,7 @@ import { ApiKeyService } from "../auth/api-keys"; · 5 unmodified lines
12	import { UserStoreService } from "../auth/context";	12	import { UserStoreService } from "../auth/context";
13	import type { Session } from "../auth/middleware";	13	import type { Session } from "../auth/middleware";
14	import { WorkOSClient } from "../auth/workos";	14	import { WorkOSClient } from "../auth/workos";
		15	import { ensureOrganizationBackfilled, mirrorInvitedMember } from "../auth/mirror-feeders";
15	import { WorkOsMirror, mirrorMembershipFromWorkOs } from "../auth/workos-mirror";	16	import { WorkOsMirror, mirrorMembershipFromWorkOs } from "../auth/workos-mirror";
16	import { ORG_SELECTOR_HEADER, authorizeOrganizationSelector } from "../auth/organization";	17	import { ORG_SELECTOR_HEADER, authorizeOrganizationSelector } from "../auth/organization";
17	import { AutumnService } from "../extensions/billing/service";	18	import { AutumnService } from "../extensions/billing/service";
@@ -66,7 +67,13 @@ const toAccountError = () => Effect.fail(new AccountError({ message: "Account re · 48 unmodified lines
66	export const workosAccountProvider: Layer.Layer<	67	export const workosAccountProvider: Layer.Layer<
67	AccountProvider,	68	AccountProvider,
68	never,	69	never,
69	WorkOSClient \| UserStoreService \| WorkOsMirror \| ApiKeyService \| AutumnService \| AccountCaller	70	\| WorkOSClient
		71	\| UserStoreService
		72	\| WorkOsMirror
		73	\| MemberDirectory
		74	\| ApiKeyService
		75	\| AutumnService
		76	\| AccountCaller
70	> = Layer.effect(AccountProvider)(	77	> = Layer.effect(AccountProvider)(
71	Effect.gen(function* () {	78	Effect.gen(function* () {
72	const workos = yield* WorkOSClient;	79	const workos = yield* WorkOSClient;
@@ -77,6 +84,10 @@ export const workosAccountProvider: Layer.Layer< · 4 unmodified lines
77	// written through to the local mirror so the member list and the seat	84	// written through to the local mirror so the member list and the seat
78	// count read the change without waiting for the Events reconciler.	85	// count read the change without waiting for the Events reconciler.
79	const mirror = yield* WorkOsMirror;	86	const mirror = yield* WorkOsMirror;
		87	// Membership READS come from the mirror through the shared directory: the
		88	// member list and the seat count are one local query each, never a
		89	// WorkOS read per member.
		90	const directory = yield* MemberDirectory;
80		91
81	// The caller, resolved once per request by the cookie-only session	92	// The caller, resolved once per request by the cookie-only session
82	// middleware (account-api.ts) — the same credential `SessionAuthLive`	93	// middleware (account-api.ts) — the same credential `SessionAuthLive`
@@ -85,10 +96,12 @@ export const workosAccountProvider: Layer.Layer< · 2 unmodified lines
85	const caller = yield* AccountCaller;	96	const caller = yield* AccountCaller;
86		97
87	// Capture the resolved service context once so the method bodies — which	98	// Capture the resolved service context once so the method bodies — which
88	// call `authorizeOrganization` (yields `WorkOSClient` + `UserStoreService`) —	99	// call `authorizeOrganization` (yields `WorkOSClient` + `UserStoreService`),
89	// can be erased to `R = never`, as the neutral AccountProvider shape	100	// the mirror feeders, and the seat reporter — can be erased to `R = never`,
90	// requires. Provided per method below.	101	// as the neutral AccountProvider shape requires. Provided per method below.
91	const ctx = yield* Effect.context<WorkOSClient \| UserStoreService \| AutumnService>();	102	const ctx = yield* Effect.context<
		103	WorkOSClient \| UserStoreService \| AutumnService \| MemberDirectory \| WorkOsMirror
		104	>();
92		105
93	// Unauthenticated (missing/invalid session) => AccountUnauthorized, exactly	106	// Unauthenticated (missing/invalid session) => AccountUnauthorized, exactly
94	// as the old inline `requireSession` did.	107	// as the old inline `requireSession` did.
@@ -145,7 +158,14 @@ export const workosAccountProvider: Layer.Layer< · 50 unmodified lines
145	return membership;	158	return membership;
146	});	159	});
147		160
148	// Mirror of org/handlers `getMemberSeats` — live seat usage from WorkOS.	161	// Seat usage: memberships from the local directory (active + pending, the
		162	// `members` default), pending invitations live from WorkOS — invitations
		163	// are not mirrored. The directory is trusted for a COUNT only once this
		164	// organization's membership list has been scanned from WorkOS in full:
		165	// login and write-through record single memberships, so an organization
		166	// the one-off backfill did not cover holds a partial list, and counting
		167	// it would admit invitations past the plan limit. The scan runs here,
		168	// once, when the organization's mark is missing.
149	const getMemberSeats = (organizationId: string) =>	169	const getMemberSeats = (organizationId: string) =>
150	Effect.gen(function* () {	170	Effect.gen(function* () {
151	const customer = yield* autumn.use((client) =>	171	const customer = yield* autumn.use((client) =>
@@ -154,15 +174,16 @@ export const workosAccountProvider: Layer.Layer< · 2 unmodified lines
154	const planId = selectActiveMemberLimitPlan(customer.subscriptions);	174	const planId = selectActiveMemberLimitPlan(customer.subscriptions);
155	const limit = getMemberLimitForPlan(planId);	175	const limit = getMemberLimitForPlan(planId);
156		176
157	// `listOrgMembers` returns active members AND pending memberships (an	177	yield* ensureOrganizationBackfilled(organizationId).pipe(Effect.provideContext(ctx));
158	// invited user shows up as status "pending"); `listPendingInvitations`	178	// The directory reports active members AND pending memberships (an
		179	// invited user is mirrored with status "pending"); `listPendingInvitations`
159	// returns the same invited users again. `countSeatsUsed` dedupes them	180	// returns the same invited users again. `countSeatsUsed` dedupes them
160	// so an outstanding invite is not counted twice.	181	// so an outstanding invite is not counted twice.
161	const memberships = yield* workos.listOrgMembers(organizationId);	182	const memberships = yield* directory.members(organizationId);
162	const invitations = yield* workos.listPendingInvitations(organizationId);	183	const invitations = yield* workos.listPendingInvitations(organizationId);
163		184
164	return {	185	return {
165	used: countSeatsUsed(memberships.data, invitations.data.length),	186	used: countSeatsUsed(memberships, invitations.data.length),
166	granted: limit ?? 0,	187	granted: limit ?? 0,
167	unlimited: limit === null,	188	unlimited: limit === null,
168	};	189	};
@@ -328,29 +349,23 @@ export const workosAccountProvider: Layer.Layer< · 159 unmodified lines
328	Effect.catchCause(() => Effect.succeed({ used: 0, granted: 0, unlimited: false })),	349	Effect.catchCause(() => Effect.succeed({ used: 0, granted: 0, unlimited: false })),
329	);	350	);
330		351
331	const memberships = yield* workos	352	// One directory read (active + pending, ordered by email) with the
332	.listOrgMembers(org.id)	353	// profile already joined — no per-member WorkOS user fetch.
333	.pipe(Effect.catchTag("WorkOSError", toAccountError));	354	const directoryMembers = yield* directory
334		355	.members(org.id)
335	const members = yield* Effect.all(	356	.pipe(Effect.catchTag("MemberDirectoryError", toAccountError));
336	memberships.data.map((m) =>	357
337	Effect.gen(function* () {	358	const members = directoryMembers.map((m) => ({
338	const user = yield* workos.getUser(m.userId);	359	id: m.membershipId,
339	return {	360	userId: m.accountId,
340	id: m.id,	361	email: m.email,
341	userId: m.userId,	362	name: m.name,
342	email: user.email,	363	avatarUrl: m.avatarUrl,
343	name: [user.firstName, user.lastName].filter(Boolean).join(" ") \|\| null,	364	role: m.role,
344	avatarUrl: user.profilePictureUrl ?? null,	365	status: m.status,
345	role: m.role?.slug ?? "member",	366	lastActiveAt: m.lastActiveAt === null ? null : new Date(m.lastActiveAt).toISOString(),
346	status: m.status,	367	isCurrentUser: m.accountId === session.accountId,
347	lastActiveAt: user.lastSignInAt ?? null,	368	}));
348	isCurrentUser: m.userId === session.accountId,
349	};
350	}),
351	),
352	{ concurrency: 5 },
353	).pipe(Effect.catchTag("WorkOSError", toAccountError));
354		369
355	return { members, seats };	370	return { members, seats };
356	}),	371	}),
@@ -378,6 +393,23 @@ export const workosAccountProvider: Layer.Layer< · 21 unmodified lines
378	...(body.roleSlug ? { roleSlug: body.roleSlug } : {}),	393	...(body.roleSlug ? { roleSlug: body.roleSlug } : {}),
379	})	394	})
380	.pipe(Effect.catchTag("WorkOSError", toAccountError));	395	.pipe(Effect.catchTag("WorkOSError", toAccountError));
		396	// Write-through: WorkOS creates a PENDING membership for the invitee
		397	// alongside the invitation, and the member list (the "Invited" row
		398	// and its revoke button) reads memberships from the mirror only, so
		399	// the row must land now — the Events reconciler is not on this path.
		400	const mirrored = yield* mirrorInvitedMember(org.id, invitation.email).pipe(
		401	Effect.provideContext(ctx),
		402	Effect.catchTags({
		403	WorkOSError: toAccountError,
		404	WorkOsMirrorError: toAccountError,
		405	}),
		406	);
		407	if (!mirrored) {
		408	yield* Effect.logWarning("inviteMember: no pending membership for the invitee yet", {
		409	organizationId: org.id,
		410	invitationId: invitation.id,
		411	});
		412	}
381	return { id: invitation.id, email: invitation.email };	413	return { id: invitation.id, email: invitation.email };
382	}),	414	}),
383		415

apps/cloud/src/admin/admin-users-api.ts+32−134

@@ -25,28 +25,24 @@ · 24 unmodified lines
25	// every query by that tenant.	25	// every query by that tenant.
26	// ---------------------------------------------------------------------------	26	// ---------------------------------------------------------------------------
27		27
28	import { env } from "cloudflare:workers";
29	import { HttpRouter } from "effect/unstable/http";	28	import { HttpRouter } from "effect/unstable/http";
30	import { Context, Effect, Layer, Option } from "effect";	29	import { Effect, Layer } from "effect";
31		30
32	import {	31	import {
33	AdminUsersProvider,	32	AdminUsersProvider,
34	DbProvider,	33	DbProvider,
35	HostConfig,	34	HostConfig,
		35	MemberDirectory,
36	PluginsProvider,	36	PluginsProvider,
		37	adminUserDirectoryFromMembers,
37	getAdminUser,	38	getAdminUser,
38	listAdminUserConnections,	39	listAdminUserConnections,
39	listAdminUsers,	40	listAdminUsers,
40	listAdminUsersWithConnections,	41	listAdminUsersWithConnections,
41	makeAdminUsersApiLayer,	42	makeAdminUsersApiLayer,
42	makePlatformExecutor,	43	makePlatformExecutor,
43	normalizeAdminUserEmail,
44	platformViewOf,	44	platformViewOf,
45	requestScopedMiddleware,	45	requestScopedMiddleware,
46	type AdminEmailResolver,
47	type AdminIdentityDirectory,
48	type AdminUserDirectory,
49	type AdminUserIdentity,
50	type AdminUsersHeaders,	46	type AdminUsersHeaders,
51	} from "@executor-js/api/server";	47	} from "@executor-js/api/server";
52	import {	48	import {
@@ -122,124 +118,6 @@ const authorizeTenant = ( · 69 unmodified lines
122	return org.id;	118	return org.id;
123	});	119	});
124		120
125	/**
126	* How many user-detail reads run at once. Matches the account plane's own
127	* member listing (`workos-account-service.ts`), which fans out the same way for
128	* the same reason.
129	*/
130	const IDENTITY_CONCURRENCY = 5;
131
132	/**
133	* Cloud's member directory: `externalId` → email/name.
134	*
135	* THE JOIN KEY is the membership's `userId` — the WorkOS `user_...` that
136	* `workos-auth-provider.ts` binds as `accountId` on every credential path, and
137	* therefore what the subject table records in `external_id`. The membership's
138	* own `id` is an `om_...` row id and joins to nothing.
139	*
140	* WHY THIS IS TWO CALLS AND NOT ONE. The membership list is read once per
141	* request and is the authority on who belongs to the org, but WorkOS's
142	* `listOrganizationMemberships` carries no user detail and offers no
143	* include/expand — email and name only exist on the user resource. The SDK does
144	* expose a batched `listUsers({ organizationId })`, but the pinned
145	* `@executor-js/emulate` WorkOS emulator serves only `GET
146	* /user_management/users/:id`, so taking that path would leave every cloud e2e
147	* user unnamed. So: ONE membership read per request, then user detail fetched
148	* only for the ids ON THIS PAGE — never for the whole org, and never once per
149	* row of some larger list. An id that is not an active/pending member is not
150	* fetched at all and reports absent identity, which is the honest answer for a
151	* member who left while their connections remain.
152	*/
153	const identityDirectory =
154	(organizationId: string, context: Context.Context<WorkOSClient>): AdminIdentityDirectory =>
155	(externalIds) =>
156	Effect.gen(function* () {
157	const workos = yield* WorkOSClient;
158	const memberships = yield* workos.listOrgMembers(organizationId);
159	const wanted = new Set(externalIds);
160	const memberIds = memberships.data
161	.map((membership) => membership.userId)
162	.filter((userId) => wanted.has(userId));
163
164	const resolved = yield* Effect.all(
165	memberIds.map((userId) =>
166	workos.getUser(userId).pipe(
167	Effect.map(
168	(user) =>
169	[
170	userId,
171	{
172	email: user.email,
173	displayName: [user.firstName, user.lastName].filter(Boolean).join(" ") \|\| null,
174	},
175	] as const,
176	),
177	// One unreadable user must not cost the whole page its names.
178	Effect.catchCause(() => Effect.succeed(null)),
179	),
180	),
181	{ concurrency: IDENTITY_CONCURRENCY },
182	);
183
184	const identities = new Map<string, AdminUserIdentity>();
185	for (const entry of resolved) if (entry) identities.set(entry[0], entry[1]);
186	return identities;
187	}).pipe(Effect.provideContext(context));
188
189	/**
190	* Cloud's REVERSE directory lookup: email → the WorkOS `user_...` id.
191	*
192	* Production asks WorkOS for the email AND organization in one request. Both
193	* filters matter: email makes the lookup indexed rather than one `getUser`
194	* request per member, while organization keeps the reverse lookup bound to the
195	* same tenant as the platform view.
196	*
197	* The pinned `@executor-js/emulate` WorkOS emulator has no list-users route.
198	* `WORKOS_API_URL` is the explicit test/dev emulator override, so that path
199	* retains the membership scan until the emulator supports the production
200	* query. The fallback still starts from the tenant's membership list and can
201	* never return a user from another organization.
202	*
203	* CASING: WorkOS preserves whatever casing an email was created with (and the
204	* emulator compares byte-exact), so the directory value is normalized here
205	* before comparison, against an argument the seam already normalized.
206	*/
207	export const emailResolver =
208	(organizationId: string, context: Context.Context<WorkOSClient>): AdminEmailResolver =>
209	(email) =>
210	Effect.gen(function* () {
211	const workos = yield* WorkOSClient;
212
213	if (!env.WORKOS_API_URL) {
214	const users = yield* workos.listUsers({ email, organizationId });
215	return users.data[0]?.id ?? null;
216	}
217
218	const memberships = yield* workos.listOrgMembers(organizationId);
219	const userIds = memberships.data.map((membership) => membership.userId);
220
221	// Emulator compatibility only. Short-circuit once the normalized email
222	// matches so the fallback makes as few unsupported-detail reads as it can.
223	const match = yield* Effect.findFirst(userIds, (userId) =>
224	workos.getUser(userId).pipe(
225	Effect.map((user) => normalizeAdminUserEmail(user.email ?? "") === email),
226	// One unreadable user must not fail the whole lookup — it simply
227	// cannot be the match.
228	Effect.catchCause(() => Effect.succeed(false)),
229	),
230	);
231	return Option.getOrNull(match);
232	}).pipe(Effect.provideContext(context));
233
234	/** Both directions of cloud's directory, built once per authorized request. */
235	const userDirectory = (
236	organizationId: string,
237	context: Context.Context<WorkOSClient>,
238	): AdminUserDirectory => ({
239	identities: identityDirectory(organizationId, context),
240	resolveEmail: emailResolver(organizationId, context),
241	});
242
243	/**	121	/**
244	* Authorize, then run `body` against the tenant's platform view.	122	* Authorize, then run `body` against the tenant's platform view.
245	*	123	*
@@ -264,8 +142,9 @@ const withPlatformView = <A, E extends AdminUsersError \| AdminUserNotFound = Adm · 18 unmodified lines
264	const executor = yield* makePlatformExecutor(organizationId).pipe(	142	const executor = yield* makePlatformExecutor(organizationId).pipe(
265	Effect.mapError(() => new AdminUsersError({ message: "Failed to open the platform view" })),	143	Effect.mapError(() => new AdminUsersError({ message: "Failed to open the platform view" })),
266	);	144	);
267	// The authorized tenant is handed to the body so an identity join reads the	145	// The authorized tenant is handed to the body so the directory reads the
268	// SAME org the reads are scoped to — never one named by client input.	146	// SAME org the storage reads are scoped to — never one named by client
		147	// input.
269	return yield* Effect.ensuring(	148	return yield* Effect.ensuring(
270	body(executor, organizationId),	149	body(executor, organizationId),
271	executor.close().pipe(Effect.ignore),	150	executor.close().pipe(Effect.ignore),
@@ -275,22 +154,40 @@ const withPlatformView = <A, E extends AdminUsersError \| AdminUserNotFound = Adm · 3 unmodified lines
275	/**	154	/**
276	* Cloud's `AdminUsersProvider`, built per request so the platform executor	155	* Cloud's `AdminUsersProvider`, built per request so the platform executor
277	* closes over the per-request postgres socket.	156	* closes over the per-request postgres socket.
		157	*
		158	* Identity (email/name per row), the `?email=` resolver and the `?search=`
		159	* match all come from the shared `MemberDirectory` — cloud's is the LOCAL
		160	* membership mirror (`auth/member-directory.ts`), so an admin page costs one
		161	* indexed query per direction and never a WorkOS read per member. The
		162	* directory is per-request too (it reads the same postgres socket), which is
		163	* why it is captured from the request context rather than at boot.
278	*/	164	*/
279	export const workosAdminUsersProvider: Layer.Layer<	165	export const workosAdminUsersProvider: Layer.Layer<
280	AdminUsersProvider,	166	AdminUsersProvider,
281	never,	167	never,
282	WorkOSClient \| ApiKeyService \| UserStoreService \| DbProvider \| PluginsProvider \| HostConfig	168	\| WorkOSClient
		169	\| ApiKeyService
		170	\| UserStoreService
		171	\| MemberDirectory
		172	\| DbProvider
		173	\| PluginsProvider
		174	\| HostConfig
283	> = Layer.effect(AdminUsersProvider)(	175	> = Layer.effect(AdminUsersProvider)(
284	Effect.gen(function* () {	176	Effect.gen(function* () {
285	const context = yield* Effect.context<	177	const context = yield* Effect.context<
286	WorkOSClient \| ApiKeyService \| UserStoreService \| DbProvider \| PluginsProvider \| HostConfig	178	WorkOSClient \| ApiKeyService \| UserStoreService \| DbProvider \| PluginsProvider \| HostConfig
287	>();	179	>();
		180	const directory = yield* MemberDirectory;
		181	// The authorized tenant is what scopes the directory, so every read below
		182	// asks the same org the platform view was opened for.
		183	const userDirectory = (organizationId: string) =>
		184	adminUserDirectoryFromMembers(directory, organizationId);
288	return AdminUsersProvider.of({	185	return AdminUsersProvider.of({
289	listUsers: (headers, options) =>	186	listUsers: (headers, options) =>
290	withPlatformView(headers, (executor, organizationId) =>	187	withPlatformView(headers, (executor, organizationId) =>
291	platformViewOf(executor).pipe(	188	platformViewOf(executor).pipe(
292	Effect.flatMap((admin) =>	189	Effect.flatMap((admin) =>
293	listAdminUsers(admin, options, userDirectory(organizationId, context)),	190	listAdminUsers(admin, options, userDirectory(organizationId)),
294	),	191	),
295	),	192	),
296	).pipe(Effect.provideContext(context)),	193	).pipe(Effect.provideContext(context)),
@@ -298,7 +195,7 @@ export const workosAdminUsersProvider: Layer.Layer< · 1 unmodified line
298	withPlatformView(headers, (executor, organizationId) =>	195	withPlatformView(headers, (executor, organizationId) =>
299	platformViewOf(executor).pipe(	196	platformViewOf(executor).pipe(
300	Effect.flatMap((admin) =>	197	Effect.flatMap((admin) =>
301	listAdminUsersWithConnections(admin, options, userDirectory(organizationId, context)),	198	listAdminUsersWithConnections(admin, options, userDirectory(organizationId)),
302	),	199	),
303	),	200	),
304	).pipe(Effect.provideContext(context)),	201	).pipe(Effect.provideContext(context)),
@@ -312,7 +209,7 @@ export const workosAdminUsersProvider: Layer.Layer< · 7 unmodified lines
312	withPlatformView(headers, (executor, organizationId) =>	209	withPlatformView(headers, (executor, organizationId) =>
313	platformViewOf(executor).pipe(	210	platformViewOf(executor).pipe(
314	Effect.flatMap((admin) =>	211	Effect.flatMap((admin) =>
315	getAdminUser(admin, identifier, userDirectory(organizationId, context)),	212	getAdminUser(admin, identifier, userDirectory(organizationId)),
316	),	213	),
317	),	214	),
318	).pipe(Effect.provideContext(context)),	215	).pipe(Effect.provideContext(context)),
@@ -322,8 +219,9 @@ export const workosAdminUsersProvider: Layer.Layer< · 3 unmodified lines
322		219
323	// Builds the provider per request, providing it to the handlers. Long-lived	220	// Builds the provider per request, providing it to the handlers. Long-lived
324	// `WorkOSClient \| ApiKeyService` come from the surrounding boot context; the	221	// `WorkOSClient \| ApiKeyService` come from the surrounding boot context; the
325	// per-request `DbService`/`UserStoreService` (and the execution seams built	222	// per-request `DbService`/`UserStoreService`/`MemberDirectory` (and the
326	// over them) are supplied by the combined `requestScopedMiddleware`.	223	// execution seams built over them) are supplied by the combined
		224	// `requestScopedMiddleware`.
327	const AdminUsersProviderMiddleware = HttpRouter.middleware<{ provides: AdminUsersProvider }>()(	225	const AdminUsersProviderMiddleware = HttpRouter.middleware<{ provides: AdminUsersProvider }>()(
328	Effect.gen(function* () {	226	Effect.gen(function* () {
329	const longLived = yield* Effect.context<WorkOSClient \| ApiKeyService>();	227	const longLived = yield* Effect.context<WorkOSClient \| ApiKeyService>();
@@ -348,7 +246,7 @@ const AdminUsersProviderMiddleware = HttpRouter.middleware<{ provides: AdminUser · 18 unmodified lines
348	* `/api` prefix as the rest of the cloud router.	246	* `/api` prefix as the rest of the cloud router.
349	*/	247	*/
350	export const makeCloudAdminUsersRoutes = (	248	export const makeCloudAdminUsersRoutes = (
351	rsLive: Layer.Layer<DbService \| UserStoreService>,	249	rsLive: Layer.Layer<DbService \| UserStoreService \| MemberDirectory>,
352	options: Parameters<typeof makeAdminUsersApiLayer>[1] = {},	250	options: Parameters<typeof makeAdminUsersApiLayer>[1] = {},
353	) =>	251	) =>
354	makeAdminUsersApiLayer(	252	makeAdminUsersApiLayer(

apps/cloud/src/admin/admin-users-email.node.test.ts+0−127

@@ -1,127 +0,0 @@
1	import { env } from "cloudflare:workers";
2	import { expect, it } from "@effect/vitest";
3	import { Data, Effect, Layer } from "effect";
4
5	import { WorkOSClient, type WorkOSClientService } from "../auth/workos";
6	import { emailResolver } from "./admin-users-api";
7
8	// Cloud's REVERSE directory lookup: email -> the WorkOS `user_...` id that the
9	// subject table records in `external_id`. Production resolves it with one
10	// tenant-scoped list-users query. The WorkOS emulator lacks that route, so
11	// tests/dev retain the membership-backed scan exercised below.
12
13	const ORG = "org_placeholder";
14	const OTHER_ORG = "org_other";
15
16	class WorkOSUnavailable extends Data.TaggedError("WorkOSUnavailable")<{
17	readonly userId: string;
18	}> {}
19
20	const DIRECTORY = [
21	// Same email in another tenant must never win either lookup path.
22	{ id: "user_foreign", email: "ada@placeholder.test", organizationId: OTHER_ORG },
23	// WorkOS preserves submitted casing, while the resolver seam is normalized.
24	{ id: "user_ada", email: "Ada@Placeholder.test", organizationId: ORG },
25	{ id: "user_grace", email: "grace@placeholder.test", organizationId: ORG },
26	{ id: "user_nameless", email: null, organizationId: ORG },
27	] as const;
28
29	const stubWorkOS = (calls: string[], unreadableUserIds: ReadonlySet<string>) =>
30	Layer.succeed(
31	WorkOSClient,
32	new Proxy({} as WorkOSClientService, {
33	get: (_target, prop) => {
34	if (prop === "listUsers") {
35	return (params: { email: string; organizationId: string }) => {
36	calls.push(`listUsers:${params.organizationId}:${params.email}`);
37	return Effect.succeed({
38	data: DIRECTORY.filter(
39	(user) =>
40	user.organizationId === params.organizationId &&
41	user.email?.toLowerCase() === params.email,
42	),
43	});
44	};
45	}
46	if (prop === "listOrgMembers") {
47	return (organizationId: string) => {
48	calls.push(`listOrgMembers:${organizationId}`);
49	return Effect.succeed({
50	data: DIRECTORY.filter((user) => user.organizationId === organizationId).map(
51	(user) => ({ userId: user.id, organizationId }),
52	),
53	});
54	};
55	}
56	if (prop === "getUser") {
57	return (userId: string) => {
58	calls.push(`getUser:${userId}`);
59	if (unreadableUserIds.has(userId)) {
60	return Effect.fail(new WorkOSUnavailable({ userId }));
61	}
62	const user = DIRECTORY.find((candidate) => candidate.id === userId);
63	if (!user) return Effect.die(`unexpected user ${userId}`);
64	return Effect.succeed(user);
65	};
66	}
67	return () => Effect.die(`unexpected WorkOSClient.${String(prop)} call`);
68	},
69	}),
70	);
71
72	const resolve = (
73	email: string,
74	calls: string[],
75	emulator = false,
76	unreadableUserIds: ReadonlySet<string> = new Set(),
77	) => {
78	const previousApiUrl = env.WORKOS_API_URL;
79	return Effect.gen(function* () {
80	yield* Effect.sync(() =>
81	Object.assign(env, {
82	WORKOS_API_URL: emulator ? "http://workos-emulator.invalid" : undefined,
83	}),
84	);
85	const context = yield* Effect.context<WorkOSClient>();
86	return yield* emailResolver(ORG, context)(email);
87	}).pipe(
88	Effect.provide(stubWorkOS(calls, unreadableUserIds)),
89	Effect.ensuring(Effect.sync(() => Object.assign(env, { WORKOS_API_URL: previousApiUrl }))),
90	);
91	};
92
93	it.effect("resolves an email with one tenant-scoped WorkOS query", () =>
94	Effect.gen(function* () {
95	const calls: string[] = [];
96	expect(yield* resolve("ada@placeholder.test", calls)).toBe("user_ada");
97	expect(calls).toEqual([`listUsers:${ORG}:ada@placeholder.test`]);
98	}),
99	);
100
101	it.effect("returns null from one query when the organization has no matching email", () =>
102	Effect.gen(function* () {
103	const calls: string[] = [];
104	expect(yield* resolve("nobody@placeholder.test", calls)).toBeNull();
105	expect(calls).toEqual([`listUsers:${ORG}:nobody@placeholder.test`]);
106	}),
107	);
108
109	it.effect("keeps the emulator fallback tenant-scoped and case-insensitive", () =>
110	Effect.gen(function* () {
111	const calls: string[] = [];
112	expect(yield* resolve("ada@placeholder.test", calls, true)).toBe("user_ada");
113	expect(calls).toEqual([`listOrgMembers:${ORG}`, "getUser:user_ada"]);
114	expect(calls).not.toContain("getUser:user_foreign");
115	expect(calls.some((call) => call.startsWith("listUsers:"))).toBe(false);
116	}),
117	);
118
119	it.effect("lets the emulator fallback continue past one unreadable member", () =>
120	Effect.gen(function* () {
121	const calls: string[] = [];
122	expect(yield* resolve("grace@placeholder.test", calls, true, new Set(["user_ada"]))).toBe(
123	"user_grace",
124	);
125	expect(calls).toEqual([`listOrgMembers:${ORG}`, "getUser:user_ada", "getUser:user_grace"]);
126	}),
127	);

apps/cloud/src/api/layers.ts+13−3

 import { HttpServer } from "effect/unstable/http";
 import { Layer } from "effect";
-import { makeProtectedApiLayer, requestScopedMiddleware } from "@executor-js/api/server";
+import {
+  makeProtectedApiLayer,
+  requestScopedMiddleware,
+  type MemberDirectory,
+} from "@executor-js/api/server";
 import { SessionAuthLive } from "../auth/middleware-live";
 import { UserStoreService } from "../auth/context";
+import { cloudMemberDirectoryLayer } from "../auth/member-directory";
 import { WorkOsMirror } from "../auth/workos-mirror";
 import {
   CloudAuthPublicHandlers,
 const DbLive = DbService.Live;
 const UserStoreLive = UserStoreService.Live.pipe(Layer.provide(DbLive));
 const WorkOsMirrorLive = WorkOsMirror.Live.pipe(Layer.provide(DbLive));
+// The shared `MemberDirectory` read seam over the membership mirror — the
+// same per-request socket the mirror writes through.
+const MemberDirectoryLive = cloudMemberDirectoryLayer.pipe(Layer.provide(DbLive));
 // Per-request layer. Anything that opens an I/O object (postgres.js socket,
 // fetch stream readers, anything backed by a `Writable`) MUST live here —
 // `provideRequestScoped` rebuilds it per request so Cloudflare Workers'
 // I/O isolation is satisfied. See `api.request-scope.test.ts`.
-export const RequestScopedServicesLive = Layer.mergeAll(DbLive, UserStoreLive, WorkOsMirrorLive);
+export const RequestScopedServicesLive: Layer.Layer<
+  DbService | UserStoreService | WorkOsMirror | MemberDirectory
+> = Layer.mergeAll(DbLive, UserStoreLive, WorkOsMirrorLive, MemberDirectoryLive);
 // Boot-scoped layer. Built once at worker boot, reused across requests.
 // Safe for config, in-memory caches, the global tracer provider, and
 // handler reads it for the free-organizations-per-user limit gate — one of the
 // few app-only billing touchpoints. (It is NOT on the neutral boot core.)
 export const makeNonProtectedApiLive = (
-  rsLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror>,
+  rsLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror | MemberDirectory>,
 ) =>
   HttpApiBuilder.layer(NonProtectedApi).pipe(
     Layer.provide(Layer.mergeAll(CloudAuthPublicHandlers, CloudSessionAuthHandlers)),

apps/cloud/src/api/router.ts+6−2

 import { Layer } from "effect";
 import { HttpRouter } from "effect/unstable/http";
-import { RouterConfigLive, requestScopedMiddleware } from "@executor-js/api/server";
+import {
+  RouterConfigLive,
+  requestScopedMiddleware,
+  type MemberDirectory,
+} from "@executor-js/api/server";
 import { UserStoreService } from "../auth/context";
 import { WorkOsMirror } from "../auth/workos-mirror";
 // assert per-request semantics — see
 // `apps/cloud/src/api.request-scope.node.test.ts`.
 export const makeApiLive = (
-  requestScopedLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror>,
+  requestScopedLive: Layer.Layer<DbService | UserStoreService | WorkOsMirror | MemberDirectory>,
 ) => {
   const BillingRoutesLive = AutumnRoutesLive.pipe(
     Layer.provide(requestScopedMiddleware(requestScopedLive).layer),

apps/cloud/src/auth/mirror-feeders.node.test.ts+360−11

@@ -12,11 +12,20 @@ · 11 unmodified lines
12	// - the callback picks the landing org from that same list: a returnTo	12	// - the callback picks the landing org from that same list: a returnTo
13	// slug or last-org cookie lands only in an ACTIVE membership, an unknown	13	// slug or last-org cookie lands only in an ACTIVE membership, an unknown
14	// or pending one falls through	14	// or pending one falls through
		15	// - `inviteMember` mirrors the PENDING membership WorkOS created for the
		16	// invitee (found by email among the org's pending memberships), so the
		17	// member list shows the invite and can revoke it
15	// - `removeMember` tombstones the mirror row after the WorkOS delete,	18	// - `removeMember` tombstones the mirror row after the WorkOS delete,
16	// stamped with the membership's last WorkOS state (never a local clock),	19	// stamped with the membership's last WorkOS state (never a local clock),
17	// so a replay of the membership as it was before the delete cannot	20	// so a replay of the membership as it was before the delete cannot
18	// restore it while a replacement WorkOS created meanwhile is accepted	21	// restore it while a replacement WorkOS created meanwhile is accepted
19	// - `updateMemberRole` writes the role WorkOS returned	22	// - `updateMemberRole` writes the role WorkOS returned
		23	// - the seat gate trusts the mirror's count only for an organization whose
		24	// membership list was scanned from WorkOS in full: an unmarked one is
		25	// scanned first (once), so a partial mirror never admits an invite past
		26	// the plan limit
		27	// - the seat reporter scans an unmarked organization before counting and
		28	// never re-scans a marked one
20	// - the backfill mirrors every org's members and counts what it wrote,	29	// - the backfill mirrors every org's members and counts what it wrote,
21	// writes nothing on a dry run, converges on a re-run, tombstones a	30	// writes nothing on a dry run, converges on a re-run, tombstones a
22	// membership WorkOS no longer lists — but never one written after its	31	// membership WorkOS no longer lists — but never one written after its
@@ -39,10 +48,11 @@ · 16 unmodified lines
39		48
40	import { describe, expect, it } from "@effect/vitest";	49	import { describe, expect, it } from "@effect/vitest";
41	import { sql } from "drizzle-orm";	50	import { sql } from "drizzle-orm";
42	import { Effect, Exit, Fiber, Latch, Layer } from "effect";	51	import { Effect, Exit, Fiber, Latch, Layer, Option } from "effect";
43	import { HttpRouter, HttpServer } from "effect/unstable/http";	52	import { HttpRouter, HttpServer } from "effect/unstable/http";
44	import { HttpApiBuilder } from "effect/unstable/httpapi";	53	import { HttpApiBuilder } from "effect/unstable/httpapi";
45		54
		55	import { AccountForbidden } from "@executor-js/api";
46	import {	56	import {
47	AccountProvider,	57	AccountProvider,
48	MemberDirectory,	58	MemberDirectory,
@@ -53,6 +63,7 @@ import { · 4 unmodified lines
53	import { AccountCaller, workosAccountProvider } from "../account/workos-account-service";	63	import { AccountCaller, workosAccountProvider } from "../account/workos-account-service";
54	import { RequestScopedServicesLive } from "../api/layers";	64	import { RequestScopedServicesLive } from "../api/layers";
55	import { DbService } from "../db/db";	65	import { DbService } from "../db/db";
		66	import { forkReportMemberSeats } from "../extensions/billing/member-seats";
56	import { AutumnService } from "../extensions/billing/service";	67	import { AutumnService } from "../extensions/billing/service";
57	import { ApiKeyService } from "./api-keys";	68	import { ApiKeyService } from "./api-keys";
58	import { UserStoreService } from "./context";	69	import { UserStoreService } from "./context";
@@ -210,13 +221,21 @@ describe("login callback", () => { · 151 unmodified lines
210	listMetadata: { before: null, after: null },	221	listMetadata: { before: null, after: null },
211	});	222	});
212	},	223	},
213	// The forked seat recount after login.	224	// The landing org's seat recount scans the org from WorkOS the first
214	listOrgMembers: () =>	225	// time it is counted (its per-org backfill mark is missing); the
215	Effect.succeed({	226	// scan lists the org's members and fetches each user.
		227	listOrgMembers: (organizationId) => {
		228	calls.push(`listOrgMembers:${organizationId}`);
		229	return Effect.succeed({
216	object: "list" as const,	230	object: "list" as const,
217	data: [] as never[],	231	data: listed.filter((m) => m.organizationId === organizationId) as never[],
218	listMetadata: { before: null, after: null },	232	listMetadata: { before: null, after: null },
219	}),	233	});
		234	},
		235	getUser: (id) => {
		236	calls.push(`getUser:${id}`);
		237	return Effect.succeed(workosUser(id) as never);
		238	},
220	refreshSession: (_sealed, organizationId) => {	239	refreshSession: (_sealed, organizationId) => {
221	refreshedInto.push(organizationId);	240	refreshedInto.push(organizationId);
222	return Effect.succeed("sealed-refreshed");	241	return Effect.succeed("sealed-refreshed");
@@ -268,7 +287,17 @@ describe("login callback", () => { · 45 unmodified lines
268	const response = await handler(callbackRequest({}));	287	const response = await handler(callbackRequest({}));
269		288
270	expect(response.status).toBe(302);	289	expect(response.status).toBe(302);
271	expect(calls, "one membership list for the whole callback").toEqual([	290	expect(
		291	calls,
		292	"one membership list for the callback itself; the landing org, never scanned, is scanned once for its seat count",
		293	).toEqual([
		294	`listUserMemberships:${userId}`,
		295	`listOrgMembers:${activeOrg}`,
		296	`getUser:${userId}`,
		297	]);
		298	calls.length = 0;
		299	expect((await handler(callbackRequest({}))).status).toBe(302);
		300	expect(calls, "a second sign-in lists memberships only: the org is now marked").toEqual([
272	`listUserMemberships:${userId}`,	301	`listUserMemberships:${userId}`,
273	]);	302	]);
274		303
@@ -542,7 +571,14 @@ describe("account service writes through to the mirror", () => { · 267 unmodified lines
542	* Provided around the WHOLE test body so the postgres socket outlives the	571	* Provided around the WHOLE test body so the postgres socket outlives the
543	* provider call under test.	572	* provider call under test.
544	*/	573	*/
545	const providerLayer = (org: string, deleted: string[]) => {	574	const providerLayer = (
		575	org: string,
		576	deleted: string[],
		577	options: {
		578	readonly workos?: Partial<WorkOSClientService>;
		579	readonly autumn?: Layer.Layer<AutumnService>;
		580	} = {},
		581	) => {
546	const list = (data: readonly unknown[]) =>	582	const list = (data: readonly unknown[]) =>
547	Effect.succeed({	583	Effect.succeed({
548	object: "list" as const,	584	object: "list" as const,
@@ -550,6 +586,7 @@ describe("account service writes through to the mirror", () => { · 1 unmodified line
550	listMetadata: { before: null, after: null },	586	listMetadata: { before: null, after: null },
551	});	587	});
552	const workos = stubWorkOS({	588	const workos = stubWorkOS({
		589	...options.workos,
553	listUserMemberships: (userId) => list([workosMembership(userId, org)]),	590	listUserMemberships: (userId) => list([workosMembership(userId, org)]),
554	getUserOrgMembership: (organizationId, userId) =>	591	getUserOrgMembership: (organizationId, userId) =>
555	Effect.succeed(	592	Effect.succeed(
@@ -571,7 +608,6 @@ describe("account service writes through to the mirror", () => { · 15 unmodified lines
571	updatedAt: T2,	608	updatedAt: T2,
572	}) as never,	609	}) as never,
573	),	610	),
574	listOrgMembers: () => list([]),
575	});	611	});
576	// The test database serves ONE connection at a time, so the seed, the	612	// The test database serves ONE connection at a time, so the seed, the
577	// provider, and the directory read all share this layer's socket.	613	// provider, and the directory read all share this layer's socket.
@@ -585,7 +621,7 @@ describe("account service writes through to the mirror", () => { · 7 unmodified lines
585	Layer.mergeAll(	621	Layer.mergeAll(
586	workos,	622	workos,
587	stubApiKeys,	623	stubApiKeys,
588	stubAutumn,	624	options.autumn ?? stubAutumn,
589	Layer.succeed(AccountCaller)({ session: session(ADMIN) }),	625	Layer.succeed(AccountCaller)({ session: session(ADMIN) }),
590	),	626	),
591	),	627	),
@@ -595,7 +631,13 @@ describe("account service writes through to the mirror", () => { · 3 unmodified lines
595	};	631	};
596		632
597	// TARGET as an existing member of `org`, seeded through the live mirror.	633	// TARGET as an existing member of `org`, seeded through the live mirror.
598	const seedTarget = (org: string) =>	634	// The org is marked backfilled (as the one-off backfill leaves every org)
		635	// unless a test wants the unscanned state, so a seat count reads the mirror
		636	// rather than scanning WorkOS.
		637	const seedTarget = (
		638	org: string,
		639	options: { readonly backfilled: boolean } = { backfilled: true },
		640	) =>
599	Effect.gen(function* () {	641	Effect.gen(function* () {
600	const users = yield* UserStoreService;	642	const users = yield* UserStoreService;
601	const mirror = yield* WorkOsMirror;	643	const mirror = yield* WorkOsMirror;
@@ -614,11 +656,175 @@ describe("account service writes through to the mirror", () => { · 12 unmodified lines
614	status: "active",	656	status: "active",
615	updatedAt: new Date(T1),	657	updatedAt: new Date(T1),
616	});	658	});
		659	if (options.backfilled) {
		660	// An empty listing at T1 (nothing to tombstone: TARGET's row is
		661	// stamped T1, not before it) marks the org scanned as of T1.
		662	yield* mirror.applyOrganizationScan({
		663	organizationId: org,
		664	listedAt: new Date(T1),
		665	members: [],
		666	});
		667	}
617	});	668	});
618		669
619	const membersOf = (org: string) =>	670	const membersOf = (org: string) =>
620	Effect.flatMap(MemberDirectory.asEffect(), (directory) => directory.members(org));	671	Effect.flatMap(MemberDirectory.asEffect(), (directory) => directory.members(org));
621		672
		673	it.effect("inviteMember mirrors the pending membership WorkOS created for the invitee", () => {
		674	const org = freshId("org");
		675	// Two people are already invited; the new invitee is a third pending
		676	// membership, and only their user carries the invited address — with
		677	// different casing than the admin typed, as WorkOS may store it.
		678	const earlier = [freshId("user"), freshId("user")];
		679	const invitee = freshId("user");
		680	const invitedEmail = `${invitee}@placeholder.test`;
		681	const userCalls: string[] = [];
		682	// The plan gate reads the customer's plan before inviting: an unlimited
		683	// plan so the seat cap never interferes with what is under test.
		684	const teamAutumn = Layer.succeed(AutumnService)({
		685	use: () =>
		686	Effect.succeed({
		687	subscriptions: [{ planId: "team", status: "active" }],
		688	} as never),
		689	ensureCustomer: () => Effect.void,
		690	checkExecutionBalance: () => Effect.die("invite does not check balances"),
		691	trackExecution: () => Effect.void,
		692	setMemberSeats: () => Effect.void,
		693	});
		694	const layer = providerLayer(org, [], {
		695	autumn: teamAutumn,
		696	workos: {
		697	listPendingInvitations: () =>
		698	Effect.succeed({
		699	object: "list" as const,
		700	data: [] as never[],
		701	listMetadata: { before: null, after: null },
		702	}),
		703	sendInvitation: ({ email }) =>
		704	Effect.succeed({
		705	id: `invitation_${invitee}`,
		706	email: email.toUpperCase(),
		707	} as never),
		708	listOrgMembers: (organizationId, statuses) => {
		709	expect(organizationId).toBe(org);
		710	expect(statuses, "only the pending set is listed").toEqual(["pending"]);
		711	return Effect.succeed({
		712	object: "list" as const,
		713	data: [...earlier, invitee].map((userId) =>
		714	workosMembership(userId, org, { status: "pending" }),
		715	) as never[],
		716	listMetadata: { before: null, after: null },
		717	});
		718	},
		719	getUser: (userId) =>
		720	Effect.sync(() => {
		721	userCalls.push(userId);
		722	return workosUser(userId, {
		723	firstName: "Invited",
		724	lastName: "Person",
		725	}) as never;
		726	}),
		727	},
		728	});
		729	return Effect.gen(function* () {
		730	yield* seedTarget(org);
		731	const account = yield* AccountProvider;
		732
		733	const result = yield* account.inviteMember(
		734	{ [ORG_SELECTOR_HEADER]: org },
		735	{ email: invitedEmail },
		736	);
		737
		738	expect(result.id).toBe(`invitation_${invitee}`);
		739	const members = yield* membersOf(org);
		740	const pending = members.find((m) => m.status === "pending");
		741	expect(pending, "the invitee appears as a pending member").toMatchObject({
		742	accountId: invitee,
		743	membershipId: `om_${invitee}_${org}`,
		744	email: invitedEmail,
		745	name: "Invited Person",
		746	role: "member",
		747	});
		748	expect(
		749	members.filter((m) => m.status === "pending"),
		750	"only the invitee's pending membership is mirrored, not the other pending ones",
		751	).toHaveLength(1);
		752	expect(
		753	userCalls.sort(),
		754	"one getUser per pending membership, bounded to the pending set",
		755	).toEqual([...earlier, invitee].sort());
		756	}).pipe(Effect.provide(layer));
		757	});
		758
		759	it.effect(
		760	"inviteMember scans an organization the backfill never covered before counting its seats, once",
		761	() => {
		762	const org = freshId("org");
		763	const listed: string[] = [];
		764	// A free plan (limit 3). The mirror holds ONE member of the org (TARGET)
		765	// and the org is unmarked; WorkOS lists three. Only a count taken after
		766	// the scan refuses the invite.
		767	const freeAutumn = Layer.succeed(AutumnService)({
		768	use: () => Effect.succeed({ subscriptions: [] } as never),
		769	ensureCustomer: () => Effect.void,
		770	checkExecutionBalance: () => Effect.die("invite does not check balances"),
		771	trackExecution: () => Effect.void,
		772	setMemberSeats: () => Effect.void,
		773	});
		774	const others = [freshId("user"), freshId("user")];
		775	const layer = providerLayer(org, [], {
		776	autumn: freeAutumn,
		777	workos: {
		778	listPendingInvitations: () =>
		779	Effect.succeed({
		780	object: "list" as const,
		781	data: [] as never[],
		782	listMetadata: { before: null, after: null },
		783	}),
		784	listOrgMembers: (organizationId, statuses) => {
		785	listed.push(organizationId);
		786	expect(statuses, "the scan lists every status, inactive included").toEqual([
		787	"active",
		788	"pending",
		789	"inactive",
		790	]);
		791	return Effect.succeed({
		792	object: "list" as const,
		793	data: [TARGET, ...others].map((userId) => workosMembership(userId, org)) as never[],
		794	listMetadata: { before: null, after: null },
		795	});
		796	},
		797	getUser: (userId) => Effect.succeed(workosUser(userId) as never),
		798	sendInvitation: () =>
		799	Effect.die("the plan gate refuses before WorkOS is asked to invite"),
		800	},
		801	});
		802	return Effect.gen(function* () {
		803	yield* seedTarget(org, { backfilled: false });
		804	const account = yield* AccountProvider;
		805	const invite = () =>
		806	Effect.flip(
		807	account.inviteMember({ [ORG_SELECTOR_HEADER]: org }, { email: "new@placeholder.test" }),
		808	);
		809
		810	const error = yield* invite();
		811	expect(error).toBeInstanceOf(AccountForbidden);
		812	expect(error).toMatchObject({
		813	message: expect.stringContaining("Your plan includes 3 members"),
		814	});
		815	expect(listed, "the org was scanned from WorkOS before it was counted").toEqual([org]);
		816	expect(
		817	(yield* membersOf(org)).map((m) => m.accountId).sort(),
		818	"and the scan filled the mirror",
		819	).toEqual([TARGET, ...others].sort());
		820
		821	const again = yield* invite();
		822	expect(again).toBeInstanceOf(AccountForbidden);
		823	expect(listed, "a marked org is never scanned again").toEqual([org]);
		824	}).pipe(Effect.provide(layer));
		825	},
		826	);
		827
622	it.effect("removeMember tombstones the mirror row after the WorkOS delete", () => {	828	it.effect("removeMember tombstones the mirror row after the WorkOS delete", () => {
623	const org = freshId("org");	829	const org = freshId("org");
624	const deleted: string[] = [];	830	const deleted: string[] = [];
@@ -688,6 +894,149 @@ describe("account service writes through to the mirror", () => { · 63 unmodified lines
688	});	894	});
689	});	895	});
690		896
		897	describe("seat reporter", () => {
		898	/**
		899	* A `WorkOsMirror` answering the per-org backfill mark and recording the
		900	* scan a reporter applies; every other operation is out of its reach.
		901	*/
		902	const recordingMirror = (backfilledAt: Date \| null, writes: string[]) =>
		903	Layer.succeed(WorkOsMirror)({
		904	upsertUser: () => Effect.die("the seat reporter scans, it does not upsert one by one"),
		905	upsertMembership: () => Effect.die("the seat reporter scans, it does not upsert one by one"),
		906	deleteMembership: () => Effect.die("the seat reporter does not delete"),
		907	deleteUser: () => Effect.die("the seat reporter does not delete"),
		908	getCursor: () => Effect.die("the seat reporter does not read the cursor"),
		909	applyPage: () => Effect.die("the seat reporter does not move the cursor"),
		910	applyOrganizationScan: (scan) =>
		911	Effect.sync(() => {
		912	writes.push(
		913	`applyOrganizationScan:${scan.organizationId}:${scan.members
		914	.map((member) => member.membership.id)
		915	.join(",")}`,
		916	);
		917	return Option.some({
		918	usersWritten: scan.members.length,
		919	membershipsWritten: scan.members.length,
		920	membershipsTombstoned: 0,
		921	});
		922	}),
		923	replayBoundary: () => Effect.die("the seat reporter does not run the reconciler"),
		924	setReplayBoundary: () => Effect.die("the seat reporter does not record the boundary"),
		925	backfillCompletedAt: () => Effect.die("the seat reporter does not check mirror readiness"),
		926	markBackfillCompleted: () => Effect.die("the seat reporter does not record the completion"),
		927	drainedAt: () => Effect.die("the seat reporter does not check mirror readiness"),
		928	markDrained: () => Effect.die("the seat reporter does not run the reconciler"),
		929	organizationBackfilledAt: () => Effect.succeed(backfilledAt),
		930	} satisfies WorkOsMirrorShape);
		931
		932	/** A directory holding `active` active members and one pending one. */
		933	const directoryWith = (org: string, active: number) =>
		934	Layer.succeed(MemberDirectory)({
		935	membership: () => Effect.die("the seat reporter lists, it does not look up"),
		936	membersById: () => Effect.die("the seat reporter lists, it does not look up"),
		937	findByEmail: () => Effect.die("the seat reporter lists, it does not look up"),
		938	members: (organizationId, query) => {
		939	expect(organizationId).toBe(org);
		940	expect(query?.statuses, "billed seats are active members only").toEqual(["active"]);
		941	return Effect.succeed(
		942	Array.from({ length: active }, (_, i) => ({
		943	accountId: `user_${i}`,
		944	membershipId: `om_${i}`,
		945	organizationId,
		946	email: null,
		947	name: null,
		948	avatarUrl: null,
		949	role: "member",
		950	status: "active" as const,
		951	lastActiveAt: null,
		952	})),
		953	);
		954	},
		955	});
		956
		957	const report = (
		958	org: string,
		959	backfilledAt: Date \| null,
		960	active: number,
		961	workos: Partial<WorkOSClientService> = {},
		962	) =>
		963	Effect.gen(function* () {
		964	const reported: { organizationId: string; seats: number }[] = [];
		965	const writes: string[] = [];
		966	const recording = Layer.succeed(AutumnService)({
		967	use: () => Effect.die("the seat reporter sets seats, it does not read"),
		968	ensureCustomer: () => Effect.void,
		969	checkExecutionBalance: () => Effect.die("the seat reporter does not check balances"),
		970	trackExecution: () => Effect.void,
		971	setMemberSeats: (organizationId, seats) =>
		972	Effect.sync(() => {
		973	reported.push({ organizationId, seats });
		974	}),
		975	});
		976	yield* forkReportMemberSeats(org).pipe(
		977	Effect.provide(
		978	Layer.mergeAll(
		979	recordingMirror(backfilledAt, writes),
		980	directoryWith(org, active),
		981	recording,
		982	stubWorkOS(workos),
		983	),
		984	),
		985	);
		986	// The Autumn call is forked; it is synchronous here, so it has landed.
		987	return { reported, writes };
		988	});
		989
		990	it.effect(
		991	"sets the active member count of a scanned organization without touching WorkOS",
		992	() => {
		993	const org = freshId("org");
		994	return Effect.gen(function* () {
		995	const { reported, writes } = yield* report(org, new Date(T1), 3);
		996	expect(reported).toEqual([{ organizationId: org, seats: 3 }]);
		997	expect(writes, "a marked organization is not scanned").toEqual([]);
		998	});
		999	},
		1000	);
		1001
		1002	it.effect("scans an organization the backfill never covered before counting it", () => {
		1003	const org = freshId("org");
		1004	const member = freshId("user");
		1005	return Effect.gen(function* () {
		1006	const { reported, writes } = yield* report(org, null, 2, {
		1007	listOrgMembers: (organizationId, statuses) => {
		1008	expect(organizationId).toBe(org);
		1009	// Inactive memberships included: a scan that skipped them would
		1010	// tombstone them under their ids and refuse their reactivation.
		1011	expect(statuses).toEqual(["active", "pending", "inactive"]);
		1012	return Effect.succeed({
		1013	object: "list" as const,
		1014	data: [workosMembership(member, org)] as never[],
		1015	listMetadata: { before: null, after: null },
		1016	});
		1017	},
		1018	getUser: (userId) => Effect.succeed(workosUser(userId) as never),
		1019	});
		1020	expect(
		1021	writes,
		1022	"the scan fills the mirror and marks the organization, then the count is read",
		1023	).toEqual([`applyOrganizationScan:${org}:om_${member}_${org}`]);
		1024	expect(reported).toEqual([{ organizationId: org, seats: 2 }]);
		1025	});
		1026	});
		1027
		1028	it.effect("pushes no count when the scan fails: a partial count is never billed", () => {
		1029	const org = freshId("org");
		1030	return Effect.gen(function* () {
		1031	const { reported, writes } = yield* report(org, null, 2, {
		1032	listOrgMembers: () => Effect.fail(new WorkOSError({ status: 503 })),
		1033	});
		1034	expect(reported).toEqual([]);
		1035	expect(writes, "nothing is marked").toEqual([]);
		1036	});
		1037	});
		1038	});
		1039
691	describe("backfill", () => {	1040	describe("backfill", () => {
692	/** A fake WorkOS holding `orgs` → members, counting `getUser` calls. */	1041	/** A fake WorkOS holding `orgs` → members, counting `getUser` calls. */
693	const source = (orgs: ReadonlyMap<string, readonly FakeMembership[]>, userCalls: string[]) => ({	1042	const source = (orgs: ReadonlyMap<string, readonly FakeMembership[]>, userCalls: string[]) => ({

apps/cloud/src/auth/mirror-feeders.ts+109−3

@@ -5,14 +5,21 @@ · 4 unmodified lines
5	// Each feeder takes the WorkOS payload the caller ALREADY holds (the	5	// Each feeder takes the WorkOS payload the caller ALREADY holds (the
6	// authenticated user, the membership list the callback fetches to pick a	6	// authenticated user, the membership list the callback fetches to pick a
7	// landing org, the membership a write returned) so feeding the mirror never	7	// landing org, the membership a write returned) so feeding the mirror never
8	// adds a WorkOS read. Mirror failures fail the request: the mirror is the	8	// adds a WorkOS read — except the two writes whose WorkOS response is not the
9	// membership read path, so a login that could not record its memberships is	9	// membership they changed: invitation acceptance (`auth/handlers.ts` reads
10	// not a login that finished.	10	// the activated membership back) and sending an invitation
		11	// (`mirrorInvitedMember` below reads the pending one WorkOS created). Both
		12	// are rare, admin-driven paths. Mirror failures fail the request: the mirror
		13	// is the membership read path, so a login that could not record its
		14	// memberships is not a login that finished.
11	// ---------------------------------------------------------------------------	15	// ---------------------------------------------------------------------------
12		16
13	import { Effect } from "effect";	17	import { Effect } from "effect";
14		18
		19	import { normalizeAdminUserEmail } from "@executor-js/api/server";
		20
15	import { UserStoreService } from "./context";	21	import { UserStoreService } from "./context";
		22	import { WorkOSClient } from "./workos";
16	import {	23	import {
17	WorkOsMirror,	24	WorkOsMirror,
18	mirrorMembershipFromWorkOs,	25	mirrorMembershipFromWorkOs,
@@ -20,6 +27,7 @@ import { · 1 unmodified line
20	type WorkOsMembershipPayload,	27	type WorkOsMembershipPayload,
21	type WorkOsUserPayload,	28	type WorkOsUserPayload,
22	} from "./workos-mirror";	29	} from "./workos-mirror";
		30	import { backfillOrganization } from "./workos-mirror-backfill";
23		31
24	/**	32	/**
25	* A membership as WorkOS lists it for a user: carries the organization's name,	33	* A membership as WorkOS lists it for a user: carries the organization's name,
@@ -78,3 +86,101 @@ export const mirrorMembership = (membership: WorkOsMembershipPayload) => · 52 unmodified lines
78	Effect.flatMap(WorkOsMirror.asEffect(), (mirror) =>	86	Effect.flatMap(WorkOsMirror.asEffect(), (mirror) =>
79	mirror.upsertMembership(mirrorMembershipFromWorkOs(membership)),	87	mirror.upsertMembership(mirrorMembershipFromWorkOs(membership)),
80	);	88	);
		89
		90	// Bounded fan-out for the per-invitee `getUser` calls, matching the backfill:
		91	// enough to overlap WorkOS round-trips, low enough to stay clear of its rate
		92	// limit.
		93	const USER_FETCH_CONCURRENCY = 5;
		94
		95	/**
		96	* Record the PENDING membership WorkOS creates for an invitee the moment an
		97	* organization invites them — the row the member list shows as "Invited" and
		98	* the admin revokes an outstanding invite through. `sendInvitation` returns
		99	* the invitation, not that membership, so this reads it back: it lists the
		100	* organization's pending memberships (WorkOS has no lookup by email that the
		101	* emulator serves) and fetches their users, five at a time, until one carries
		102	* the invited email. Bounded by the pending set, so an organization with
		103	* many active members pays nothing per member.
		104	*
		105	* `false` when no pending membership carried the email — WorkOS created none
		106	* (the address may already hold a membership) or has not yet — which the
		107	* caller treats as a warning, not a failure: the Events reconciler lands
		108	* whatever WorkOS did create.
		109	*/
		110	export const mirrorInvitedMember = Effect.fn("workos_mirror.invitedMember")(function* (
		111	organizationId: string,
		112	invitedEmail: string,
		113	) {
		114	const workos = yield* WorkOSClient;
		115	const mirror = yield* WorkOsMirror;
		116	const wanted = normalizeAdminUserEmail(invitedEmail);
		117	const pending = yield* workos.listOrgMembers(organizationId, ["pending"]);
		118	for (let start = 0; start < pending.data.length; start += USER_FETCH_CONCURRENCY) {
		119	const batch = pending.data.slice(start, start + USER_FETCH_CONCURRENCY);
		120	const candidates = yield* Effect.forEach(
		121	batch,
		122	(membership) =>
		123	Effect.map(workos.getUser(membership.userId), (user) => ({
		124	membership,
		125	user,
		126	})),
		127	{ concurrency: USER_FETCH_CONCURRENCY },
		128	);
		129	const match = candidates.find(
		130	(candidate) => normalizeAdminUserEmail(candidate.user.email) === wanted,
		131	);
		132	if (match === undefined) continue;
		133	yield* mirror.upsertUser(mirrorUserFromWorkOs(match.user));
		134	yield* mirror.upsertMembership(mirrorMembershipFromWorkOs(match.membership));
		135	return true;
		136	}
		137	return false;
		138	});
		139
		140	/**
		141	* Make sure the organization's membership list has been scanned from WorkOS
		142	* in full before a COUNT read from the mirror is trusted. Login records only
		143	* the caller's own memberships and write-through only the one it changed,
		144	* so an organization the one-off backfill did not cover — mirrored lazily
		145	* by a request, or created after the backfill ran — holds a partial list
		146	* until it is scanned. The per-organization mark
		147	* (`organizations.backfilled_at`) says whether that scan has happened; when
		148	* it is missing, this runs the scan now (`backfillOrganization`: one
		149	* membership listing plus one `getUser` per member, then the mark), so the
		150	* caller's count is complete. Returns `true` when a scan ran. A scan that
		151	* fails marks nothing, so the next count tries again.
		152	*/
		153	export const ensureOrganizationBackfilled = Effect.fn("workos_mirror.ensureOrganizationBackfilled")(
		154	function* (organizationId: string) {
		155	const mirror = yield* WorkOsMirror;
		156	const backfilledAt = yield* mirror.organizationBackfilledAt(organizationId);
		157	if (backfilledAt !== null) return false;
		158	const workos = yield* WorkOSClient;
		159	yield* Effect.logInfo(
		160	"workos_mirror: organization not yet backfilled; scanning it from WorkOS",
		161	{
		162	organizationId,
		163	},
		164	);
		165	yield* backfillOrganization(
		166	{
		167	// EVERY status, as the scan source requires: the scan tombstones
		168	// whatever its listing lacks, and a tombstone is keyed to the
		169	// membership id for good — so a listing that skipped the inactive
		170	// ones (the wrapper's active + pending default, the seat-occupying
		171	// set) would tombstone a membership WorkOS merely deactivated and
		172	// refuse its reactivation under the same id forever.
		173	listOrgMembers: (id) =>
		174	Effect.map(
		175	workos.listOrgMembers(id, ["active", "pending", "inactive"]),
		176	(list) => list.data,
		177	),
		178	getUser: (id) => workos.getUser(id),
		179	},
		180	mirror,
		181	organizationId,
		182	{ dryRun: false },
		183	);
		184	return true;
		185	},
		186	);

apps/cloud/src/auth/workos-callback-state.node.test.ts+27−5

 import { HttpApiBuilder } from "effect/unstable/httpapi";
 import { HttpApi } from "effect/unstable/httpapi";
+import { MemberDirectory } from "@executor-js/api/server";
 import { CloudAuthPublicHandlers } from "./handlers";
 import { CloudAuthPublicApi } from "./api";
 import { UserStoreService } from "./context";
       if (prop === "listUserMemberships") {
         return () => Effect.succeed({ data: [] });
       }
-      if (prop === "listOrgMembers") {
-        return () => Effect.succeed({ data: [{ status: "active" }] });
-      }
       return () => Effect.die(`unexpected WorkOSClient.${String(prop)} call`);
     },
   }),
 });
 // The callback records the sign-in (user + memberships) in the membership
-// mirror; every other mirror operation is out of this route's reach.
+// mirror, and its forked seat recount reads the backfill marker and the
+// landed org's active members from it; every other operation is out of this
+// route's reach.
 const stubMirror = Layer.succeed(WorkOsMirror)({
   upsertUser: () => Effect.succeed(true),
   upsertMembership: () => Effect.succeed(true),
   markBackfillCompleted: () => Effect.die("the callback does not run the backfill"),
   drainedAt: () => Effect.die("the callback does not check mirror readiness"),
   markDrained: () => Effect.die("the callback does not run the reconciler"),
-  organizationBackfilledAt: () => Effect.die("the callback does not report seats"),
+  organizationBackfilledAt: () => Effect.succeed(new Date()),
+});
+const stubDirectory = Layer.succeed(MemberDirectory)({
+  membership: () => Effect.die("the callback does not look up one membership"),
+  membersById: () => Effect.die("the callback does not batch members"),
+  findByEmail: () => Effect.die("the callback does not resolve emails"),
+  members: (organizationId) =>
+    Effect.succeed([
+      {
+        accountId: STUB_USER_ID,
+        membershipId: `om_${STUB_USER_ID}`,
+        organizationId,
+        email: null,
+        name: null,
+        avatarUrl: null,
+        role: "member",
+        status: "active" as const,
+        lastActiveAt: null,
+      },
+    ]),
 });
 // Only the public group is under test; the session group (and its SessionAuth
   Layer.provide(stubWorkOS),
   Layer.provide(stubUsers),
   Layer.provide(stubMirror),
+  Layer.provide(stubDirectory),
   Layer.provide(AutumnService.Default),
   Layer.provide(HttpServer.layerServices),
 );

apps/cloud/src/auth/workos.ts+12−14

   WorkOS,
   type Event as WorkOSEvent,
   type EventName as WorkOSEventName,
+  type OrganizationMembershipStatus,
 } from "@workos-inc/node/worker";
 import { defaults as ironDefaults, unseal as unsealIron } from "iron-webcrypto";
 import { decodeJwt, jwtVerify } from "jose";
     deleteApiKey: (id: string) =>
       use("apiKeys.deleteApiKey", (wos) => wos.apiKeys.deleteApiKey(id)),
-    /** List organization memberships with user details. */
+    /**
-    listOrgMembers: (organizationId: string) =>
+     * An organization's memberships, all pages. Defaults to active + pending
+     * (the seat-occupying set); pass `statuses` to narrow — the invite
+     * write-through lists only `pending` to find the membership WorkOS
+     * created for the invitee.
+     */
+    listOrgMembers: (
+      organizationId: string,
+      statuses: readonly OrganizationMembershipStatus[] = ["active", "pending"],
+    ) =>
       use("userManagement.listOrganizationMemberships", async (wos) =>
         collectWorkOSList(
           await wos.userManagement.listOrganizationMemberships({
             organizationId,
-            statuses: ["active", "pending"],
+            statuses: [...statuses],
           }),
         ),
       ),
     getUser: (userId: string) =>
       use("userManagement.getUser", (wos) => wos.userManagement.getUser(userId)),
-    /** List users matching an email within one organization. */
-    listUsers: (params: { email: string; organizationId: string }) =>
-      use("userManagement.listUsers", async (wos) =>
-        collectWorkOSList(
-          await wos.userManagement.listUsers({
-            email: params.email,
-            organizationId: params.organizationId,
-          }),
-        ),
-      ),
     /** Send an organization invitation. */
     sendInvitation: (params: { email: string; organizationId: string; roleSlug?: string }) =>
       use("userManagement.sendInvitation", (wos) =>

apps/cloud/src/extensions/billing/member-seats.ts+49−29

 // ---------------------------------------------------------------------------
-// Seat-count reporting — the WorkOS → Autumn reconciliation for seat billing
+// Seat-count reporting — the membership mirror → Autumn reconciliation for
+// seat billing
 // ---------------------------------------------------------------------------
 import { Effect } from "effect";
 import { waitUntil } from "cloudflare:workers";
-import { WorkOSClient } from "../../auth/workos";
+import { MemberDirectory } from "@executor-js/api/server";
+import { ensureOrganizationBackfilled } from "../../auth/mirror-feeders";
+import type { WorkOSClient } from "../../auth/workos";
+import type { WorkOsMirror } from "../../auth/workos-mirror";
 import { AutumnService } from "./service";
 /**
  * Seats change through paths the app never sees a mutation for (invitation
  * acceptance in AuthKit, SSO JIT provisioning, join by domain, WorkOS
  * dashboard edits), so this reconciles from a full recount rather than
- * tracking deltas. It runs after in-app membership mutations AND on every
+ * tracking deltas. The count comes from the local membership mirror through
- * login callback, so drift from out-of-band changes heals on the next
+ * the shared `MemberDirectory`: every in-app membership mutation writes
- * sign-in. Fire-and-forget-safe: errors are logged, never surfaced.
+ * through to the mirror BEFORE calling this, and out-of-band changes land via
+ * login and the Events reconciler, so the recount reads the change on the
+ * next sign-in exactly as it did against WorkOS — without a WorkOS read.
+ *
+ * The Autumn call runs off the calling request's critical path: Cloudflare
+ * owns its promise through `waitUntil`, so the recount can finish after the
+ * response, and billing never stalls or fails a user-facing request. Errors
+ * are logged, never surfaced.
+ *
+ * The count is a PARTIAL one until THIS organization's membership list has
+ * been scanned from WorkOS in full (the one-off backfill, or the on-demand
+ * scan below): before that, the mirror holds only the members who signed in
+ * or were changed since the mirror shipped. Because the Autumn write is an
+ * authoritative SET, pushing a partial count would under-bill the
+ * organization, so the recount first makes sure the organization is
+ * backfilled (`ensureOrganizationBackfilled`: a scan runs now when its
+ * per-organization mark is missing) and only then counts. The plan gate
+ * (`reserveMemberSlot`) goes through the same step, so it never admits an
+ * invite past the plan limit on a partial mirror.
+ *
+ * The COUNT is read inline, not in the fork: `MemberDirectory` is per-request
+ * (it holds the request's postgres socket, which Cloudflare Workers' I/O
+ * isolation ties to the request), so a forked fiber reading it could outlive
+ * the socket. One indexed local query is cheap enough to pay inline; only the
+ * Autumn call — over the boot-scoped `AutumnService` — is forked, so the
+ * forked fiber captures nothing request-scoped.
  */
-export const reportMemberSeats = (
+export const forkReportMemberSeats = (
   organizationId: string,
-): Effect.Effect<void, never, WorkOSClient | AutumnService> =>
+): Effect.Effect<void, never, MemberDirectory | WorkOsMirror | WorkOSClient | AutumnService> =>
   Effect.gen(function* () {
-    const workos = yield* WorkOSClient;
+    const directory = yield* MemberDirectory;
     const autumn = yield* AutumnService;
-    const memberships = yield* workos.listOrgMembers(organizationId);
+    yield* ensureOrganizationBackfilled(organizationId);
-    const seats = memberships.data.filter((m) => m.status === "active").length;
+    const seats = yield* directory
-    yield* autumn.setMemberSeats(organizationId, seats);
+      .members(organizationId, { statuses: ["active"] })
+      .pipe(Effect.map((members) => members.length));
+    yield* Effect.sync(() => {
+      waitUntil(Effect.runPromise(autumn.setMemberSeats(organizationId, seats)));
+    });
   }).pipe(
     Effect.catch((error) =>
-      Effect.logWarning("reportMemberSeats: seat recount failed", { organizationId, error }),
+      Effect.logWarning("reportMemberSeats: seat recount failed", {
+        organizationId,
+        error,
+      }),
     ),
     Effect.withSpan("billing.reportMemberSeats"),
   );
-/**
- * Fork `reportMemberSeats` off the calling request, mirroring how execution
- * tracking is forked: billing must never stall or fail a user-facing
- * request. Cloudflare owns the promise through waitUntil, so the recount can
- * finish after the response. Only boot-scoped WorkOS and Autumn services are
- * captured.
- */
-export const forkReportMemberSeats = (
-  organizationId: string,
-): Effect.Effect<void, never, WorkOSClient | AutumnService> =>
-  Effect.gen(function* () {
-    const ctx = yield* Effect.context<WorkOSClient | AutumnService>();
-    yield* Effect.sync(() => {
-      waitUntil(Effect.runPromiseWith(ctx)(reportMemberSeats(organizationId)));
-    });
-  });

apps/cloud/src/extensions/routes.ts+2−2

@@ -28,7 +28,7 @@ import { HttpApiBuilder } from "effect/unstable/httpapi"; · 27 unmodified lines
28	import { HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";	28	import { HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
29		29
30	import { AccountApi, AdminUsersApi } from "@executor-js/api";	30	import { AccountApi, AdminUsersApi } from "@executor-js/api";
31	import { requestScopedMiddleware } from "@executor-js/api/server";	31	import { requestScopedMiddleware, type MemberDirectory } from "@executor-js/api/server";
32		32
33	import { UserStoreService } from "../auth/context";	33	import { UserStoreService } from "../auth/context";
34	import { WorkOsMirror } from "../auth/workos-mirror";	34	import { WorkOsMirror } from "../auth/workos-mirror";
@@ -79,7 +79,7 @@ const spec = OpenApi.fromApi(CloudOpenApi); · 44 unmodified lines
79	* core.	79	* core.
80	*/	80	*/
81	export const makeCloudExtensionRoutes = (	81	export const makeCloudExtensionRoutes = (
82	rsLive: Layer.Layer<DbService \| UserStoreService \| WorkOsMirror>,	82	rsLive: Layer.Layer<DbService \| UserStoreService \| WorkOsMirror \| MemberDirectory>,
83	) => {	83	) => {
84	// Session routes (login / callback / me / switch-org / …). Handlers yield	84	// Session routes (login / callback / me / switch-org / …). Handlers yield
85	// `UserStoreService` directly; the per-request DB combine keeps the postgres	85	// `UserStoreService` directly; the per-request DB combine keeps the postgres

apps/host-selfhost/src/account/better-auth-account-provider.ts+1−1

@@ -145,7 +145,7 @@ export const betterAuthAccountProvider: Layer.Layer<AccountProvider, never, Bett · 144 unmodified lines
145	const members = result.members.map((member) => ({	145	const members = result.members.map((member) => ({
146	id: member.id,	146	id: member.id,
147	userId: member.userId,	147	userId: member.userId,
148	email: member.user?.email ?? "",	148	email: member.user?.email ?? null,
149	name: member.user?.name ?? null,	149	name: member.user?.name ?? null,
150	avatarUrl: member.user?.image ?? null,	150	avatarUrl: member.user?.image ?? null,
151	role: member.role,	151	role: member.role,

apps/host-selfhost/src/admin/admin-users-api.ts+20−77

 //
 // The READ half is identical to cloud's: a subject-less, tenant-reach executor
 // from `makePlatformExecutor`, projected by the shared `admin/reads`. Self-host
-// is single-tenant, so the tenant is always the boot-seeded org.
+// is single-tenant, so the tenant is always the boot-seeded org. Identity
+// (email/name per row), the `?email=` resolver and the `?search=` match all
+// come from the shared `MemberDirectory` — here Better Auth's `member` + `user`
+// tables through its own adapter (`auth/member-directory.ts`), the SAME read
+// the MCP plane makes, so no plane keeps its own join.
 // ---------------------------------------------------------------------------
 import { HttpRouter } from "effect/unstable/http";
   AdminUsersProvider,
   DbProvider,
   HostConfig,
+  MemberDirectory,
   PluginsProvider,
+  adminUserDirectoryFromMembers,
   getAdminUser,
   listAdminUserConnections,
   listAdminUsers,
   listAdminUsersWithConnections,
   makeAdminUsersApiLayer,
   makePlatformExecutor,
-  normalizeAdminUserEmail,
   platformViewOf,
   requestScopedMiddleware,
-  type AdminUserDirectory,
-  type AdminUserIdentity,
   type AdminUsersHeaders,
 } from "@executor-js/api/server";
 import {
     ),
   );
-/**
- * Self-host's member directory: `externalId` → email/name.
- *
- * THE JOIN KEY is `member.userId`, the Better Auth `user.id` — precisely what
- * `auth/identity.ts` binds as `accountId` and therefore what the subject table
- * records in `external_id`. `member.id` is the organization `member` ROW id and
- * joins to nothing; the two look alike, so the choice is pinned here and in the
- * node test rather than left to a reader.
- *
- * One `listMembers` call per request: Better Auth's organization plugin already
- * attaches the `user` row to each member, so email and name arrive with the
- * membership and no per-user lookup is needed. The requested ids are not passed
- * to the call — the plugin offers no id filter, and a single-instance member
- * list is small — but the caller only reads the ids it asked for.
- *
- * Runs as the CALLER, using their own admin headers, so this reads exactly the
- * directory that session is already entitled to on `/account/members`.
- */
-const listMembers = (auth: BetterAuthHandle["auth"], headers: AdminUsersHeaders) =>
-  Effect.tryPromise(() => auth.api.listMembers({ headers: new Headers(headers) }));
-/**
- * Both directions of self-host's directory, over the SAME single `listMembers`
- * read.
- *
- * The reverse (email → `user.id`) needs no extra call and no new permission:
- * the organization plugin already attaches the `user` row to each member, so
- * the email is sitting beside the id the forward join uses. Better Auth
- * lower-cases every email it writes, but the directory value is normalized
- * anyway so this host cannot answer differently from cloud if that ever
- * changes.
- *
- * A member with no `user.email` cannot match — `null` is not an address, and
- * coercing it to "" would let an empty `?email=` select an arbitrary row.
- */
-const userDirectory = (
-  auth: BetterAuthHandle["auth"],
-  headers: AdminUsersHeaders,
-): AdminUserDirectory => ({
-  identities: () =>
-    listMembers(auth, headers).pipe(
-      Effect.map((result) => {
-        const identities = new Map<string, AdminUserIdentity>();
-        for (const member of result.members) {
-          identities.set(member.userId, {
-            email: member.user?.email ?? null,
-            displayName: member.user?.name ?? null,
-          });
-        }
-        return identities;
-      }),
-    ),
-  resolveEmail: (email) =>
-    listMembers(auth, headers).pipe(
-      Effect.map(
-        (result) =>
-          result.members.find((member) => {
-            const stored = member.user?.email;
-            return stored != null && normalizeAdminUserEmail(stored) === email;
-          })?.userId ?? null,
-      ),
-    ),
-});
 const withPlatformView = <A, E extends AdminUsersError | AdminUserNotFound = AdminUsersError>(
   headers: AdminUsersHeaders,
   organizationId: string,
 export const betterAuthAdminUsersProvider: Layer.Layer<
   AdminUsersProvider,
   never,
-  BetterAuth | DbProvider | PluginsProvider | HostConfig
+  BetterAuth | MemberDirectory | DbProvider | PluginsProvider | HostConfig
 > = Layer.effect(AdminUsersProvider)(
   Effect.gen(function* () {
     const context = yield* Effect.context<BetterAuth | DbProvider | PluginsProvider | HostConfig>();
-    const { auth, organizationId } = yield* BetterAuth;
+    const { organizationId } = yield* BetterAuth;
+    // Scoped to the INSTANCE's org — the same one the platform view is opened
+    // for, never the caller's `activeOrganizationId` (see require-admin.ts).
+    const directory = adminUserDirectoryFromMembers(yield* MemberDirectory, organizationId);
     return AdminUsersProvider.of({
       listUsers: (headers, options) =>
         withPlatformView(headers, organizationId, (executor) =>
           platformViewOf(executor).pipe(
-            Effect.flatMap((admin) => listAdminUsers(admin, options, userDirectory(auth, headers))),
+            Effect.flatMap((admin) => listAdminUsers(admin, options, directory)),
           ),
         ).pipe(Effect.provideContext(context)),
       listUsersWithConnections: (headers, options) =>
         withPlatformView(headers, organizationId, (executor) =>
           platformViewOf(executor).pipe(
-            Effect.flatMap((admin) =>
+            Effect.flatMap((admin) => listAdminUsersWithConnections(admin, options, directory)),
-              listAdminUsersWithConnections(admin, options, userDirectory(auth, headers)),
-            ),
           ),
         ).pipe(Effect.provideContext(context)),
       listUserConnections: (headers, externalId) =>
       getUser: (headers, identifier) =>
         withPlatformView(headers, organizationId, (executor) =>
           platformViewOf(executor).pipe(
-            Effect.flatMap((admin) =>
+            Effect.flatMap((admin) => getAdminUser(admin, identifier, directory)),
-              getAdminUser(admin, identifier, userDirectory(auth, headers)),
-            ),
           ),
         ).pipe(Effect.provideContext(context)),
     });
 export interface SelfHostAdminUsersApiDeps {
   readonly betterAuth: BetterAuthHandle;
+  /** The boot-built `MemberDirectory` (see `resolveAuthProviders`), so this
+   *  plane reads the same directory instance every other plane does. */
+  readonly memberDirectory: Layer.Layer<MemberDirectory>;
   readonly db: SelfHostDbHandle;
   readonly mountPrefix: `/${string}`;
 }
  */
 export const makeSelfHostAdminUsersApiLayer = ({
   betterAuth,
+  memberDirectory,
   db,
   mountPrefix,
 }: SelfHostAdminUsersApiDeps) => {
   );
   const provider = betterAuthAdminUsersProvider.pipe(
     Layer.provide(Layer.succeed(BetterAuth)(betterAuth)),
+    Layer.provide(memberDirectory),
     Layer.provide(SelfHostDbProvider),
     Layer.provide(SelfHostPluginsProvider),
     Layer.provide(SelfHostHostConfig),

apps/host-selfhost/src/app.ts+11−2

   // ---- auth providers ---------------------------------------------------
   // Better Auth: cookie/bearer/api-key identity + /api/auth handler + account
   // API + MCP OAuth seam, all over the shared libSQL handle.
-  const { identityLayer, authHandler, betterAuth } = await resolveAuthProviders(dbHandle);
+  const { identityLayer, memberDirectoryLayer, authHandler, betterAuth } =
+    await resolveAuthProviders(dbHandle);
   // ---- the in-process MCP serving seams (+ shutdown hook) ----------------
   const mcp = makeSelfHostMcpSeams(dbHandle, betterAuth, config);
         // Tenant-wide admin users API (/api/admin/users*): the owner's view of
         // who uses this instance and what they've connected. Owner/admin-gated,
         // same as the invite routes above.
-        makeSelfHostAdminUsersApiLayer({ betterAuth, db: dbHandle, mountPrefix: "/api" }),
+        makeSelfHostAdminUsersApiLayer({
+          betterAuth,
+          memberDirectory: memberDirectoryLayer,
+          db: dbHandle,
+          mountPrefix: "/api",
+        }),
         // Public system API: /api/health + /api/setup-status (unauthenticated).
         makeSelfHostSystemApiLayer({ betterAuth, db: dbHandle, mountPrefix: "/api" }),
         // Swagger UI at /docs, over the /api-prefixed spec (matches the served paths).
     // The boot-scoped context provideMerge'd under everything: the long-lived DB
     // handle (read by the DbProvider seam, Better Auth, and the MCP store) + the
     // resolved identity (captured once by the execution middleware + MCP auth)
+    // + the member directory (the shared membership read seam, boot-scoped
+    // beside identity because Better Auth's handle is an app singleton)
     // + the artifact-usage observer (this HTTP plane is the console UI's data
     // layer, so operations it serves file as `via: "ui"`).
     boot: Layer.mergeAll(
       Layer.succeed(SelfHostDb)(dbHandle),
       identityLayer,
+      memberDirectoryLayer,
       Layer.succeed(ArtifactUsageObserver)((action) =>
         selfHostAnalytics.record(`artifact_${action}`, { via: "ui" }),
       ),

apps/host-selfhost/src/auth/index.ts+11−4

 import { Layer } from "effect";
-import { IdentityProvider } from "@executor-js/api/server";
+import { IdentityProvider, MemberDirectory } from "@executor-js/api/server";
 import { loadConfig } from "../config";
 import type { SelfHostDbHandle } from "../db/self-host-db";
 import { BetterAuth, buildBetterAuth, type BetterAuthHandle } from "./better-auth";
 import { betterAuthIdentityLayer } from "./identity";
+import { betterAuthMemberDirectoryLayer } from "./member-directory";
 import { consentRedirectClientId, withClientName, withForcedMcpConsent } from "./force-mcp-consent";
 import { rewriteInvalidOrigin } from "./invalid-origin-help";
 export { BetterAuth, buildBetterAuth, type BetterAuthHandle } from "./better-auth";
 export { betterAuthIdentityLayer } from "./identity";
+export { betterAuthMemberDirectoryLayer } from "./member-directory";
 // ---------------------------------------------------------------------------
 // Resolve the self-host auth providers.
 //
 // Build the Better Auth instance over the shared libSQL file, expose its
-// `IdentityProvider` (cookie/bearer/api-key) and its web handler (mounted at
+// `IdentityProvider` (cookie/bearer/api-key), its `MemberDirectory` (the
-// /api/auth/*). Returns the live `BetterAuthHandle` so the composition root can
+// shared membership read seam over the org plugin's tables) and its web
-// build the account API and the Better Auth MCP OAuth seam.
+// handler (mounted at /api/auth/*). Returns the live `BetterAuthHandle` so the
+// composition root can build the account API and the Better Auth MCP OAuth
+// seam.
 //
 // This is the one and only production auth path. Tests that need a fake identity
 // (single-admin / header-driven) compose `ExecutorApp.make` directly through
 export interface ResolvedAuthProviders {
   /** The resolved Better Auth `IdentityProvider` seam (cookie/bearer/api-key). */
   readonly identityLayer: Layer.Layer<IdentityProvider>;
+  /** The resolved Better Auth `MemberDirectory` seam (org members + users). */
+  readonly memberDirectoryLayer: Layer.Layer<MemberDirectory>;
   /** Better Auth's web handler (`/api/auth/*`). */
   readonly authHandler: (request: Request) => Promise<Response>;
   /** The live Better Auth handle (account API + Better Auth MCP OAuth seam). */
   return {
     identityLayer: betterAuthIdentityLayer.pipe(Layer.provide(betterAuthLayer)),
+    memberDirectoryLayer: betterAuthMemberDirectoryLayer.pipe(Layer.provide(betterAuthLayer)),
     authHandler,
     betterAuth,
   };

packages/core/api/src/account/api.ts+8−1

   apiKeys: Schema.Array(ApiKeySummary),
 });
+/**
+ * One member of the caller's organization, as the host's member directory
+ * reports them. `email` is nullable: a host can hold a membership whose
+ * profile it has not yet learned (cloud mirrors the membership before the
+ * user record lands), and reporting `""` for that would let the UI render an
+ * empty address as if it were one.
+ */
 export const OrgMember = Schema.Struct({
   id: Schema.String,
   userId: Schema.String,
-  email: Schema.String,
+  email: Schema.NullOr(Schema.String),
   name: Schema.NullOr(Schema.String),
   avatarUrl: Schema.NullOr(Schema.String),
   role: Schema.String,

packages/core/api/src/admin/admin-users.test.ts+158−5

@@ -395,6 +395,7 @@ const A1_EMAIL = "a1@users.test"; · 394 unmodified lines
395	const stubUserDirectory = (options: {	395	const stubUserDirectory = (options: {
396	readonly seen?: string[][];	396	readonly seen?: string[][];
397	readonly resolved?: string[];	397	readonly resolved?: string[];
		398	readonly searched?: string[];
398	}): AdminUserDirectory => ({	399	}): AdminUserDirectory => ({
399	identities: (externalIds) => {	400	identities: (externalIds) => {
400	options.seen?.push([...externalIds]);	401	options.seen?.push([...externalIds]);
@@ -405,6 +406,13 @@ const stubUserDirectory = (options: { · 4 unmodified lines
405	// Compares a NORMALIZED stored value, the rule both real hosts follow.	406	// Compares a NORMALIZED stored value, the rule both real hosts follow.
406	return Effect.succeed(A1_EMAIL_STORED.toLowerCase() === email ? USER_A1 : null);	407	return Effect.succeed(A1_EMAIL_STORED.toLowerCase() === email ? USER_A1 : null);
407	},	408	},
		409	search: (term) => {
		410	options.searched?.push(term);
		411	// The one member the directory knows, matched on the normalized email or
		412	// the display name — the substring rule both real hosts apply.
		413	const haystack = [A1_EMAIL_STORED.toLowerCase(), "user a1"];
		414	return Effect.succeed(haystack.some((value) => value.includes(term)) ? [USER_A1] : []);
		415	},
408	});	416	});
409		417
410	/** The failure a host's directory raises — WorkOS or Better Auth being	418	/** The failure a host's directory raises — WorkOS or Better Auth being
@@ -1022,6 +1030,102 @@ describe("admin users API", () => { · 611 unmodified lines
1022	),	1030	),
1023	);	1031	);
1024		1032
		1033	// ── ?search= ──────────────────────────────────────────────────────────────
		1034
		1035	it.effect("filters the bulk lists by a name or email substring, case-insensitively", () =>
		1036	withDb((db) =>
		1037	Effect.gen(function* () {
		1038	yield* seed(db);
		1039	const searched: string[] = [];
		1040	const web = yield* webHandlerFor(
		1041	stubProvider((tenant) => platformExecutorFor(db, tenant), headerAuthorize, {
		1042	...stubUserDirectory({ searched }),
		1043	}),
		1044	);
		1045
		1046	// Part of the address, typed in the wrong case and with stray spaces:
		1047	// the handler normalizes it before the directory sees it.
		1048	const byEmail = yield* jsonOf<UsersBody>(
		1049	yield* get(web, `/admin/users?search=${encodeURIComponent(" A1@USERS ")}`, ORG_A),
		1050	);
		1051	expect(byEmail.users.map((user) => user.externalId)).toEqual([USER_A1]);
		1052	expect(byEmail.users[0]?.email, "the page still carries identity").toBe(A1_EMAIL_STORED);
		1053
		1054	// Part of the name, on the joined view.
		1055	const byName = yield* jsonOf<UsersWithConnectionsBody>(
		1056	yield* get(web, "/admin/users/with-connections?search=User%20a1", ORG_A),
		1057	);
		1058	expect(byName.users.map((user) => user.externalId)).toEqual([USER_A1]);
		1059	expect(byName.users[0]?.connections.map((c) => c.integration)).toEqual(["github"]);
		1060
		1061	// No match is an empty page, never the unfiltered tenant.
		1062	const nobody = yield* jsonOf<UsersBody>(
		1063	yield* get(web, "/admin/users?search=nobody", ORG_A),
		1064	);
		1065	expect(nobody.users).toEqual([]);
		1066
		1067	expect(searched, "one directory search per request, normalized").toEqual([
		1068	"a1@users",
		1069	"user a1",
		1070	"nobody",
		1071	]);
		1072	}),
		1073	),
		1074	);
		1075
		1076	it.effect("a blank search is no filter at all", () =>
		1077	withDb((db) =>
		1078	Effect.gen(function* () {
		1079	yield* seed(db);
		1080	const searched: string[] = [];
		1081	const web = yield* webHandlerFor(
		1082	stubProvider(
		1083	(tenant) => platformExecutorFor(db, tenant),
		1084	headerAuthorize,
		1085	stubUserDirectory({ searched }),
		1086	),
		1087	);
		1088
		1089	const body = yield* jsonOf<UsersBody>(yield* get(web, "/admin/users?search=%20%20", ORG_A));
		1090	expect(body.users.map((user) => user.externalId)).toEqual([USER_A1, USER_A2]);
		1091	expect(searched, "the directory is never asked to match whitespace").toEqual([]);
		1092	}),
		1093	),
		1094	);
		1095
		1096	it.effect("returns an empty page for a search no host directory can answer", () =>
		1097	withDb((db) =>
		1098	Effect.gen(function* () {
		1099	yield* seed(db);
		1100	// A directory with identities only: it cannot search, so a search
		1101	// filter must select nothing rather than hand back the whole tenant.
		1102	const web = yield* webHandlerFor(
		1103	stubProvider((tenant) => platformExecutorFor(db, tenant), headerAuthorize, {
		1104	identities: stubDirectory([]),
		1105	}),
		1106	);
		1107
		1108	const body = yield* jsonOf<UsersBody>(yield* get(web, "/admin/users?search=a1", ORG_A));
		1109	expect(body.users).toEqual([]);
		1110	}),
		1111	),
		1112	);
		1113
		1114	it.effect("500s when the directory search fails, rather than reporting no match", () =>
		1115	withDb((db) =>
		1116	Effect.gen(function* () {
		1117	yield* seed(db);
		1118	const web = yield* webHandlerFor(
		1119	stubProvider((tenant) => platformExecutorFor(db, tenant), headerAuthorize, {
		1120	search: () => Effect.fail(new DirectoryUnavailable({ message: "down" })),
		1121	}),
		1122	);
		1123
		1124	expect((yield* get(web, "/admin/users?search=a1", ORG_A)).status).toBe(500);
		1125	}),
		1126	),
		1127	);
		1128
1025	// A resolver OUTAGE must not read as "no such user": that is a wrong answer an	1129	// A resolver OUTAGE must not read as "no such user": that is a wrong answer an
1026	// operator would act on. Contrast with the identity join, which degrades to	1130	// operator would act on. Contrast with the identity join, which degrades to
1027	// unnamed rows precisely because it is decoration.	1131	// unnamed rows precisely because it is decoration.
@@ -1096,8 +1200,8 @@ const A_SUBJECT: AdminSubject = { · 68 unmodified lines
1096	/** An `ExecutorAdmin` that answers everything and records the reads it was	1200	/** An `ExecutorAdmin` that answers everything and records the reads it was
1097	* asked for, so a test can assert the call the filter chose. */	1201	* asked for, so a test can assert the call the filter chose. */
1098	const recordingAdmin = (calls: string[]): ExecutorAdmin => ({	1202	const recordingAdmin = (calls: string[]): ExecutorAdmin => ({
1099	listSubjects: () => {	1203	listSubjects: (options) => {
1100	calls.push("listSubjects");	1204	calls.push(`listSubjects:${options?.externalIds?.join(",") ?? "*"}`);
1101	return Effect.succeed([A_SUBJECT]);	1205	return Effect.succeed([A_SUBJECT]);
1102	},	1206	},
1103	getSubject: () => {	1207	getSubject: () => {
@@ -1108,8 +1212,8 @@ const recordingAdmin = (calls: string[]): ExecutorAdmin => ({ · 4 unmodified lines
1108	calls.push("listSubjectConnections");	1212	calls.push("listSubjectConnections");
1109	return Effect.succeed([]);	1213	return Effect.succeed([]);
1110	},	1214	},
1111	listSubjectsWithConnections: () => {	1215	listSubjectsWithConnections: (options) => {
1112	calls.push("listSubjectsWithConnections");	1216	calls.push(`listSubjectsWithConnections:${options?.externalIds?.join(",") ?? "*"}`);
1113	return Effect.succeed([{ ...A_SUBJECT, connections: [] }]);	1217	return Effect.succeed([{ ...A_SUBJECT, connections: [] }]);
1114	},	1218	},
1115	getSubjectWithConnections: () => {	1219	getSubjectWithConnections: () => {
@@ -1187,7 +1291,56 @@ describe("admin users reads — the ?email= filter is applied before the read", · 71 unmodified lines
1187	const calls: string[] = [];	1291	const calls: string[] = [];
1188	yield* listUsersWithConnections(recordingAdmin(calls), { limit: 50 }, stubUserDirectory({}));	1292	yield* listUsersWithConnections(recordingAdmin(calls), { limit: 50 }, stubUserDirectory({}));
1189		1293
1190	expect(calls).toEqual(["listSubjectsWithConnections"]);	1294	expect(calls).toEqual(["listSubjectsWithConnections:*"]);
		1295	}),
		1296	);
		1297	});
		1298
		1299	// ---------------------------------------------------------------------------
		1300	// `?search=` is FILTER-THEN-PAGE through storage: the directory names the
		1301	// matching principals, and the paged read carries exactly that set as its
		1302	// `externalIds` filter — never a page scan that is filtered afterwards.
		1303	// ---------------------------------------------------------------------------
		1304
		1305	describe("admin users reads — the ?search= filter pages the directory's matches", () => {
		1306	it.effect("hands the matched ids to the paged read, on both views", () =>
		1307	Effect.gen(function* () {
		1308	const calls: string[] = [];
		1309	const admin = recordingAdmin(calls);
		1310
		1311	yield* listUsers(admin, { search: "a1" }, stubUserDirectory({}));
		1312	yield* listUsersWithConnections(admin, { search: "user", limit: 10 }, stubUserDirectory({}));
		1313
		1314	expect(calls).toEqual([`listSubjects:${USER_A1}`, `listSubjectsWithConnections:${USER_A1}`]);
		1315	}),
		1316	);
		1317
		1318	it.effect("issues NO storage read when the directory matches nobody", () =>
		1319	Effect.gen(function* () {
		1320	const calls: string[] = [];
		1321	const body = yield* listUsersWithConnections(
		1322	recordingAdmin(calls),
		1323	{ search: "nobody" },
		1324	stubUserDirectory({}),
		1325	);
		1326
		1327	expect(calls).toEqual([]);
		1328	expect(body.users).toEqual([]);
		1329	}),
		1330	);
		1331
		1332	it.effect("lets an exact email win over a search term", () =>
		1333	Effect.gen(function* () {
		1334	const calls: string[] = [];
		1335	const searched: string[] = [];
		1336	yield* listUsers(
		1337	recordingAdmin(calls),
		1338	{ email: A1_EMAIL, search: "anything" },
		1339	stubUserDirectory({ searched }),
		1340	);
		1341
		1342	expect(calls, "the keyed read, not a search").toEqual(["getSubject"]);
		1343	expect(searched).toEqual([]);
1191	}),	1344	}),
1192	);	1345	);
1193	});	1346	});

packages/core/api/src/admin/api.ts+10−0

 // handler seam (`normalizeEmail`), which is also where the single-user path
 // parameter is normalized, so both entry points share ONE rule rather than a
 // schema transform on one and hand-rolled code on the other.
+//
+// `search` is the SUBSTRING counterpart: a case-insensitive match over each
+// member's email and name in the host's directory, for the operator who knows
+// a person's name or part of an address rather than the exact one. Like
+// `email` it narrows the fixed list shape and is applied BEFORE paging (the
+// directory names the matching principals; storage pages that set), so a
+// window on a searched list is a window on the matches. A blank term is no
+// filter. When both filters are present `email` wins: it names one principal,
+// and there is nothing left for a search to narrow.
 const AdminListQuery = Schema.Struct({
   limit: Schema.optional(
     Schema.FiniteFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 500 })),
     ),
   ),
   email: Schema.optional(Schema.String),
+  search: Schema.optional(Schema.String),
 });
 // ---------------------------------------------------------------------------

packages/core/api/src/admin/handlers.ts+14−5

 import { HttpServerRequest } from "effect/unstable/http";
 import { Effect } from "effect";
+import { normalizeMemberSearch } from "../server/member-directory";
 import { AdminUsersHttpApi } from "./api";
 import { normalizeEmail } from "./reads";
 import { AdminUsersProvider, type AdminUsersHeaders, type AdminUsersListOptions } from "./service";
 // than an explicit `undefined` overriding them.
 // `email` is normalized here rather than in the contract schema, so the filter
 // and the single-user path parameter share ONE rule (`normalizeEmail`).
+// `search` gets the directory's own rule (`normalizeMemberSearch`: the same
+// trim + lower-case, and a blank term is no filter at all — dropped here so a
+// provider never sees `search: ""`).
 const listOptions = (query: {
   readonly limit?: number | undefined;
   readonly offset?: number | undefined;
   readonly email?: string | undefined;
-}): AdminUsersListOptions => ({
+  readonly search?: string | undefined;
-  ...(query.limit === undefined ? {} : { limit: query.limit }),
+}): AdminUsersListOptions => {
-  ...(query.offset === undefined ? {} : { offset: query.offset }),
+  const search = normalizeMemberSearch(query.search);
-  ...(query.email === undefined ? {} : { email: normalizeEmail(query.email) }),
+  return {
-});
+    ...(query.limit === undefined ? {} : { limit: query.limit }),
+    ...(query.offset === undefined ? {} : { offset: query.offset }),
+    ...(query.email === undefined ? {} : { email: normalizeEmail(query.email) }),
+    ...(search === undefined ? {} : { search }),
+  };
+};
 export const AdminUsersHandlers = HttpApiBuilder.group(
   AdminUsersHttpApi,

packages/core/api/src/admin/member-directory.ts+16−7

 import type { AdminUserDirectory, AdminUserIdentity } from "./reads";
 /**
- * Both directions of the admin plane's directory over one org's
+ * Every direction of the admin plane's directory over one org's
  * {@link MemberDirectoryShape}.
  *
  * `identities` is one batched `membersById` read for the page of ids (never a
  * lookup per user); a member the org does not hold reports absent identity.
  * `resolveEmail` receives the already-normalized email the contract promises
  * and answers with the host principal id, or `null` when no member has it.
+ * `search` is one `members` read for the term, answering with the matching
+ * principal ids in directory order.
  *
- * Both read ANY membership status, not the directory's active + pending
+ * Every direction reads ANY membership status — the same reach `membersById`
- * default: this plane reports footprint, not current access. A member who was
+ * and `findByEmail` have by contract, and `search` asks for explicitly rather
- * removed while their connections remain must still be named on the users
+ * than taking `members`' active + pending default. This plane reports
- * page and findable by the address an operator has for them.
+ * footprint, not current access: a member who was deactivated while their
+ * connections remain must still be findable by the address or name an
+ * operator has for them, exactly as `?email=` already finds them.
  *
- * Both fail with `MemberDirectoryError`, which the shared reads treat as a
+ * All fail with `MemberDirectoryError`, which the shared reads treat as a
- * decorative-join outage (identities) or surface as a failed read (resolve).
+ * decorative-join outage (identities) or surface as a failed read (resolve,
+ * search).
  */
 export const adminUserDirectoryFromMembers = (
   directory: MemberDirectoryShape,
     directory
       .findByEmail(organizationId, email, MemberStatus.literals)
       .pipe(Effect.map((member) => (member === null ? null : member.accountId))),
+  search: (term) =>
+    directory
+      .members(organizationId, { search: term, statuses: MemberStatus.literals })
+      .pipe(Effect.map((members) => members.map((member) => member.accountId))),
 });

packages/core/api/src/admin/reads.ts+95−17

@@ -16,6 +16,7 @@ import { Effect } from "effect"; · 15 unmodified lines
16		16
17	import type {	17	import type {
18	AdminConnection,	18	AdminConnection,
		19	AdminListSubjectsOptions,
19	AdminSubject,	20	AdminSubject,
20	AdminSubjectWithConnections,	21	AdminSubjectWithConnections,
21	Executor,	22	Executor,
@@ -114,12 +115,27 @@ export type AdminIdentityDirectory = ( · 92 unmodified lines
114	*/	115	*/
115	export type AdminEmailResolver = (email: string) => Effect.Effect<string \| null, unknown>;	116	export type AdminEmailResolver = (email: string) => Effect.Effect<string \| null, unknown>;
116		117
117	/** Both directions of a host's member directory. Optional as a whole (a host	118	/**
118	* with no directory reports unnamed rows and cannot resolve emails), and	119	* The directory's SEARCH: a normalized term (trimmed + lower-cased, the same
119	* optional per direction. */	120	* rule `normalizeEmail` applies) → the host-auth principal ids of every member
		121	* whose email or name contains it, in the directory's own order.
		122	*
		123	* Unlike `resolveEmail` this names a SET, and the reads page that set through
		124	* storage rather than in memory: the ids go into the SDK's `externalIds`
		125	* filter and the caller's `limit`/`offset` apply there. An empty result means
		126	* no member matches, and costs no storage read. Failures are the caller's to
		127	* interpret on the same terms as `resolveEmail` — a search that cannot run
		128	* must not quietly become "nobody matches".
		129	*/
		130	export type AdminMemberSearch = (term: string) => Effect.Effect<readonly string[], unknown>;
		131
		132	/** Every direction of a host's member directory. Optional as a whole (a host
		133	* with no directory reports unnamed rows and cannot resolve emails or search),
		134	* and optional per direction. */
120	export interface AdminUserDirectory {	135	export interface AdminUserDirectory {
121	readonly identities?: AdminIdentityDirectory;	136	readonly identities?: AdminIdentityDirectory;
122	readonly resolveEmail?: AdminEmailResolver;	137	readonly resolveEmail?: AdminEmailResolver;
		138	readonly search?: AdminMemberSearch;
123	}	139	}
124		140
125	/** Identity is decoration on an operator view, not part of the answer: a	141	/** Identity is decoration on an operator view, not part of the answer: a
@@ -292,6 +308,72 @@ const selectByEmail = <T>( · 166 unmodified lines
292	return row === null ? [] : pageOf([row], options);	308	return row === null ? [] : pageOf([row], options);
293	});	309	});
294		310
		311	/**
		312	* The `?search=` read: FILTER by the directory, then PAGE through storage.
		313	*
		314	* The term names a SET of principals rather than one, so unlike `?email=` it
		315	* cannot become a keyed read — but it still must not become a page-then-filter
		316	* scan, which on a large tenant would page past every unmatched subject before
		317	* finding the first match. So the directory answers with the matching ids and
		318	* storage pages exactly that set (`externalIds` + the caller's window), which
		319	* keeps "filter, then page" as the one paging rule every filtered list here
		320	* follows.
		321	*
		322	* A host with no search direction answers nothing, for the same reason an
		323	* unanswerable `?email=` does: a filter no host can apply must return an empty
		324	* page, never an unfiltered one. A search FAILURE is a 500 on the same terms as
		325	* a resolver failure.
		326	*/
		327	const selectBySearch = <T>(
		328	directory: AdminUserDirectory,
		329	term: string,
		330	read: (externalIds: readonly string[]) => Effect.Effect<readonly T[], AdminUsersError>,
		331	): Effect.Effect<readonly T[], AdminUsersError> =>
		332	Effect.gen(function* () {
		333	const search = directory.search;
		334	if (!search) return [];
		335	const wanted = yield* search(term).pipe(
		336	Effect.mapError(() => new AdminUsersError({ message: "Failed to search the directory" })),
		337	);
		338	// Nobody matches: an empty page, and no storage read for an `in ()` that
		339	// could not match anyway.
		340	if (wanted.length === 0) return [];
		341	return yield* read(wanted);
		342	});
		343
		344	/**
		345	* Which filtered read a list request takes. `email` names ONE principal and
		346	* wins when both are present: a keyed read is the more specific answer, and
		347	* a search term beside an exact address has nothing left to narrow.
		348	*/
		349	const selectSubjects = <T>(
		350	directory: AdminUserDirectory,
		351	options: AdminUsersListOptions,
		352	reads: {
		353	readonly page: (
		354	paging: AdminListSubjectsOptions,
		355	) => Effect.Effect<readonly T[], AdminUsersError>;
		356	readonly one: (externalId: string) => Effect.Effect<T \| null, AdminUsersError>;
		357	},
		358	): Effect.Effect<readonly T[], AdminUsersError> => {
		359	if (options.email !== undefined) {
		360	return selectByEmail(directory, options.email, options, reads.one);
		361	}
		362	if (options.search !== undefined) {
		363	return selectBySearch(directory, options.search, (externalIds) =>
		364	reads.page({ ...pagingOf(options), externalIds }),
		365	);
		366	}
		367	return reads.page(pagingOf(options));
		368	};
		369
		370	/** Only the paging window — never the filters — reaches the SDK: the filters
		371	* are resolved here, and the SDK's own `externalIds` is set by this file. */
		372	const pagingOf = (options: AdminUsersListOptions): AdminListSubjectsOptions => ({
		373	...(options.limit === undefined ? {} : { limit: options.limit }),
		374	...(options.offset === undefined ? {} : { offset: options.offset }),
		375	});
		376
295	export const listUsers = (	377	export const listUsers = (
296	admin: ExecutorAdmin,	378	admin: ExecutorAdmin,
297	options: AdminUsersListOptions,	379	options: AdminUsersListOptions,
@@ -299,12 +381,10 @@ export const listUsers = ( · 1 unmodified line
299	): Effect.Effect<typeof AdminUsersResponse.Type, AdminUsersError> =>	381	): Effect.Effect<typeof AdminUsersResponse.Type, AdminUsersError> =>
300	Effect.gen(function* () {	382	Effect.gen(function* () {
301	const dir = asDirectory(directory);	383	const dir = asDirectory(directory);
302	const subjects =	384	const subjects = yield* selectSubjects(dir, options, {
303	options.email === undefined	385	page: (paging) => admin.listSubjects(paging).pipe(Effect.mapError(readFailed("users"))),
304	? yield* admin.listSubjects(options).pipe(Effect.mapError(readFailed("users")))	386	one: (externalId) => admin.getSubject(externalId).pipe(Effect.mapError(readFailed("users"))),
305	: yield* selectByEmail(dir, options.email, options, (externalId) =>	387	});
306	admin.getSubject(externalId).pipe(Effect.mapError(readFailed("users"))),
307	);
308	// One directory read for the page that was actually returned, joined in	388	// One directory read for the page that was actually returned, joined in
309	// memory — never a lookup per user.	389	// memory — never a lookup per user.
310	const identities = yield* resolveIdentities(	390	const identities = yield* resolveIdentities(
@@ -321,14 +401,12 @@ export const listUsersWithConnections = ( · 10 unmodified lines
321	): Effect.Effect<typeof AdminUsersWithConnectionsResponse.Type, AdminUsersError> =>	401	): Effect.Effect<typeof AdminUsersWithConnectionsResponse.Type, AdminUsersError> =>
322	Effect.gen(function* () {	402	Effect.gen(function* () {
323	const dir = asDirectory(directory);	403	const dir = asDirectory(directory);
324	const subjects =	404	const subjects = yield* selectSubjects(dir, options, {
325	options.email === undefined	405	page: (paging) =>
326	? yield* admin	406	admin.listSubjectsWithConnections(paging).pipe(Effect.mapError(readFailed("users"))),
327	.listSubjectsWithConnections(options)	407	one: (externalId) =>
328	.pipe(Effect.mapError(readFailed("users")))	408	admin.getSubjectWithConnections(externalId).pipe(Effect.mapError(readFailed("users"))),
329	: yield* selectByEmail(dir, options.email, options, (externalId) =>	409	});
330	admin.getSubjectWithConnections(externalId).pipe(Effect.mapError(readFailed("users"))),
331	);
332	const identities = yield* resolveIdentities(	410	const identities = yield* resolveIdentities(
333	dir.identities,	411	dir.identities,
334	subjects.map((subject) => subject.externalId),	412	subjects.map((subject) => subject.externalId),

packages/core/api/src/admin/service.ts+5−2

 export type AdminUsersHeaders = Record<string, string>;
 /** Paging and filtering, mirroring the SDK's `AdminListSubjectsOptions` plus
- *  the contract's `?email=`. The email arrives already trimmed and lower-cased
+ *  the contract's `?email=` and `?search=`. Both filters arrive already
- *  by the contract schema, so a provider never re-normalizes it. */
+ *  trimmed and lower-cased by the handler seam (a blank search is omitted
+ *  entirely), so a provider never re-normalizes them. `email` names ONE
+ *  principal and wins when both are present. */
 export interface AdminUsersListOptions {
   readonly limit?: number;
   readonly offset?: number;
   readonly email?: string;
+  readonly search?: string;
 }
 type User = typeof AdminUserResponse.Type;

packages/core/api/src/server.ts+1−0

@@ -40,6 +40,7 @@ export { · 39 unmodified lines
40	normalizeEmail as normalizeAdminUserEmail,	40	normalizeEmail as normalizeAdminUserEmail,
41	type AdminEmailResolver,	41	type AdminEmailResolver,
42	type AdminIdentityDirectory,	42	type AdminIdentityDirectory,
		43	type AdminMemberSearch,
43	type AdminUserDirectory,	44	type AdminUserDirectory,
44	type AdminUserIdentity,	45	type AdminUserIdentity,
45	} from "./admin/reads";	46	} from "./admin/reads";

packages/core/sdk/src/executor.ts+18−0

@@ -593,6 +593,14 @@ export interface AdminSubjectWithConnections extends AdminSubject { · 592 unmodified lines
593	export interface AdminListSubjectsOptions {	593	export interface AdminListSubjectsOptions {
594	readonly limit?: number;	594	readonly limit?: number;
595	readonly offset?: number;	595	readonly offset?: number;
		596	/**
		597	* Keep only subjects whose `external_id` is in this set — the host's answer
		598	* to a directory search (name or email), paged through storage rather than
		599	* in memory. An EMPTY set matches nothing; `undefined` is no filter. Paging
		600	* applies to the filtered set: "filter, then page", the same order the
		601	* `?email=` read follows.
		602	*/
		603	readonly externalIds?: readonly string[];
596	}	604	}
597		605
598	/**	606	/**
@@ -7006,8 +7014,18 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea · 6407 unmodified lines
7006	// them through independently produced a bare OFFSET, which SQLite	7014	// them through independently produced a bare OFFSET, which SQLite
7007	// rejects outright.	7015	// rejects outright.
7008	const { limit, offset } = normalizeAdminPaging(options);	7016	const { limit, offset } = normalizeAdminPaging(options);
		7017	const externalIds = options?.externalIds;
		7018	// An empty id set is a query that cannot match; answer it without a
		7019	// round trip rather than emitting `in ()`, which some drivers reject.
		7020	if (externalIds !== undefined && externalIds.length === 0) return Effect.succeed([]);
7009	return platformCore	7021	return platformCore
7010	.findMany("subject", {	7022	.findMany("subject", {
		7023	// The id filter is the ONLY predicate here; the tenant clause is
		7024	// the policy's, added to every read the same way `getSubject`
		7025	// relies on it.
		7026	...(externalIds === undefined
		7027	? {}
		7028	: { where: (b: AnyCb) => b("external_id", "in", [...externalIds]) }),
7011	// Oldest first, ties broken on the unique key so the order is	7029	// Oldest first, ties broken on the unique key so the order is
7012	// total and paging can't repeat or skip a row.	7030	// total and paging can't repeat or skip a row.
7013	orderBy: [	7031	orderBy: [

packages/core/sdk/src/platform-view.test.ts+55−0

@@ -424,6 +424,61 @@ const expectWriteRefused = <A, E extends { readonly _tag: string }>( · 423 unmodified lines
424	Effect.orDie,	424	Effect.orDie,
425	);	425	);
426		426
		427	describe("platform view — admin.listSubjects externalIds filter", () => {
		428	it.effect("keeps only the named ids, still ordered and paged through storage", () =>
		429	withDb((db) =>
		430	Effect.gen(function* () {
		431	yield* seed(db);
		432	const admin = yield* requireAdmin(yield* makePlatformExecutor(db));
		433
		434	const only = yield* admin.listSubjects({ externalIds: [SUBJECT_B] });
		435	expect(only.map((entry) => entry.externalId)).toEqual([SUBJECT_B]);
		436
		437	// Ids the tenant does not hold are simply absent — including another
		438	// tenant's subject, which the policy keeps out regardless of the filter.
		439	const mixed = yield* admin.listSubjects({
		440	externalIds: [SUBJECT_B, "user_nobody", "user_elsewhere", SUBJECT_A],
		441	});
		442	expect(mixed.map((entry) => entry.externalId).sort()).toEqual([SUBJECT_A, SUBJECT_B]);
		443
		444	// "Filter, then page": the window applies to the filtered set.
		445	const all = yield* admin.listSubjects();
		446	const second = yield* admin.listSubjects({
		447	externalIds: [SUBJECT_A, SUBJECT_B],
		448	limit: 1,
		449	offset: 1,
		450	});
		451	expect(second.map((entry) => entry.externalId)).toEqual([all[1]?.externalId]);
		452	}),
		453	),
		454	);
		455
		456	it.effect("an empty id set matches nothing, on both list reads", () =>
		457	withDb((db) =>
		458	Effect.gen(function* () {
		459	yield* seed(db);
		460	const admin = yield* requireAdmin(yield* makePlatformExecutor(db));
		461
		462	expect(yield* admin.listSubjects({ externalIds: [] })).toEqual([]);
		463	expect(yield* admin.listSubjectsWithConnections({ externalIds: [] })).toEqual([]);
		464	}),
		465	),
		466	);
		467
		468	it.effect("the joined read filters the same way and still joins connections", () =>
		469	withDb((db) =>
		470	Effect.gen(function* () {
		471	yield* seed(db);
		472	const admin = yield* requireAdmin(yield* makePlatformExecutor(db));
		473
		474	const rows = yield* admin.listSubjectsWithConnections({ externalIds: [SUBJECT_A] });
		475	expect(rows.map((entry) => entry.externalId)).toEqual([SUBJECT_A]);
		476	expect(rows[0]?.connections.length).toBeGreaterThan(0);
		477	}),
		478	),
		479	);
		480	});
		481
427	describe("platform view — read-only across every surface", () => {	482	describe("platform view — read-only across every surface", () => {
428	it.effect("refuses org-row writes through policies and oauth", () =>	483	it.effect("refuses org-row writes through policies and oauth", () =>
429	withDb((db) =>	484	withDb((db) =>

packages/react/src/api/admin-atoms.tsx+14−5

 // rejects writes at tenant reach), so there are no mutations here and every
 // atom carries the same reactivity key.
 //
-// Paging is part of the atom identity, so each page is its own cache entry and
+// Paging and the search term are part of the atom identity, so each page of
-// stepping back to a visited page is instant. `Atom.family` (not a bare arrow)
+// each search is its own cache entry and stepping back to a visited page is
-// because the page component re-derives the key object on every render — a
+// instant. `Atom.family` (not a bare arrow) because the page component
-// fresh atom per render would refetch in a loop.
+// re-derives the key object on every render — a fresh atom per render would
+// refetch in a loop.
 // ---------------------------------------------------------------------------
 /** How many users one page of the list shows. Well inside the contract's
 export interface AdminUsersPage {
   readonly limit: number;
   readonly offset: number;
+  /** The `?search=` term (name or email substring), already debounced by the
+   *  page. `""` is no filter and is sent as no param at all, so the unfiltered
+   *  list keeps one cache identity regardless of how the term was cleared. */
+  readonly search: string;
 }
 /**
  */
 export const adminUsersWithConnectionsAtom = Atom.family((page: AdminUsersPage) =>
   AdminApiClient.query("adminUsers", "listUsersWithConnections", {
-    query: { limit: page.limit + 1, offset: page.offset },
+    query: {
+      limit: page.limit + 1,
+      offset: page.offset,
+      ...(page.search === "" ? {} : { search: page.search }),
+    },
     timeToLive: "30 seconds",
     reactivityKeys: [ReactivityKey.adminUsers],
   }),

packages/react/src/pages/admin-users.tsx+117−2

@@ -1,6 +1,7 @@
1	import { useState } from "react";	1	import { useEffect, useState } from "react";
2	import { useAtomRefresh, useAtomValue } from "@effect/atom-react";	2	import { useAtomRefresh, useAtomValue } from "@effect/atom-react";
3	import { useParams } from "@tanstack/react-router";	3	import { useParams } from "@tanstack/react-router";
		4	import { SearchIcon, XIcon } from "lucide-react";
4	import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";	5	import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
5	import * as Cause from "effect/Cause";	6	import * as Cause from "effect/Cause";
6	import * as Option from "effect/Option";	7	import * as Option from "effect/Option";
@@ -18,6 +19,7 @@ import { ownerLabel } from "../api/owner-display"; · 11 unmodified lines
18	import { Button } from "../components/button";	19	import { Button } from "../components/button";
19	import { CopyButton } from "../components/copy-button";	20	import { CopyButton } from "../components/copy-button";
20	import { ErrorState } from "../components/error-state";	21	import { ErrorState } from "../components/error-state";
		22	import { Input } from "../components/input";
21	import {	23	import {
22	IntegrationFavicon,	24	IntegrationFavicon,
23	integrationInferredUrl,	25	integrationInferredUrl,
@@ -521,14 +523,94 @@ function UserDetail(props: { · 497 unmodified lines
521	});	523	});
522	}	524	}
523		525
		526	// ── Search ──────────────────────────────────────────────────────────────────
		527
		528	/** How long the typed term settles before it becomes a request. Long enough
		529	* that a typed name is one query rather than one per keystroke, short enough
		530	* to read as immediate. */
		531	const SEARCH_DEBOUNCE_MS = 250;
		532
		533	/**
		534	* The search box: what is typed, and the settled term the list actually asks
		535	* for. Two values because the request is debounced, and the input must keep
		536	* echoing keystrokes while the term catches up. Clearing bypasses the debounce
		537	* — an emptied box should show everyone at once, not after a pause.
		538	*/
		539	const useDebouncedSearch = (): {
		540	readonly typed: string;
		541	readonly term: string;
		542	readonly setTyped: (value: string) => void;
		543	readonly clear: () => void;
		544	} => {
		545	const [typed, setTypedState] = useState("");
		546	const [term, setTerm] = useState("");
		547
		548	useEffect(() => {
		549	if (typed === term) return;
		550	const handle = setTimeout(() => setTerm(typed), SEARCH_DEBOUNCE_MS);
		551	return () => clearTimeout(handle);
		552	}, [typed, term]);
		553
		554	return {
		555	typed,
		556	term,
		557	setTyped: setTypedState,
		558	clear: () => {
		559	setTypedState("");
		560	setTerm("");
		561	},
		562	};
		563	};
		564
		565	function UserSearch(props: {
		566	readonly value: string;
		567	readonly onChange: (value: string) => void;
		568	readonly onClear: () => void;
		569	}) {
		570	return (
		571	<div className="relative mb-4 min-w-0" data-slot="admin-users-search">
		572	<SearchIcon
		573	className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground"
		574	aria-hidden
		575	/>
		576	<Input
		577	type="search"
		578	value={props.value}
		579	onChange={(event) => props.onChange((event.target as HTMLInputElement).value)}
		580	onKeyDown={(event) => {
		581	if (event.key === "Escape" && props.value !== "") props.onClear();
		582	}}
		583	placeholder="Search by name or email"
		584	aria-label="Search users by name or email"
		585	className="h-9 pl-9 pr-9 text-sm [&::-webkit-search-cancel-button]:hidden"
		586	/>
		587	{props.value !== "" && (
		588	<Button
		589	type="button"
		590	variant="ghost"
		591	size="icon-xs"
		592	aria-label="Clear search"
		593	onClick={props.onClear}
		594	className="absolute right-1.5 top-1/2 -translate-y-1/2 text-muted-foreground"
		595	>
		596	<XIcon />
		597	</Button>
		598	)}
		599	</div>
		600	);
		601	}
		602
524	// ── Page ────────────────────────────────────────────────────────────────────	603	// ── Page ────────────────────────────────────────────────────────────────────
525		604
526	export function AdminUsersPage() {	605	export function AdminUsersPage() {
527	useExecutorDocumentTitle("Users");	606	useExecutorDocumentTitle("Users");
528	const [offset, setOffset] = useState(0);	607	const [offset, setOffset] = useState(0);
529	const [selected, setSelected] = useState<AdminUserRow \| null>(null);	608	const [selected, setSelected] = useState<AdminUserRow \| null>(null);
		609	const search = useDebouncedSearch();
530		610
531	const page = { limit: ADMIN_USERS_PAGE_SIZE, offset };	611	// A new term is a new list, so it starts on its first page: an offset kept
		612	// from a broader list would land past the end of a narrower one.
		613	const page = { limit: ADMIN_USERS_PAGE_SIZE, offset, search: search.term };
532	const result = useAtomValue(adminUsersWithConnectionsAtom(page));	614	const result = useAtomValue(adminUsersWithConnectionsAtom(page));
533	const refresh = useAtomRefresh(adminUsersWithConnectionsAtom(page));	615	const refresh = useAtomRefresh(adminUsersWithConnectionsAtom(page));
534	const catalog = useCatalogRows();	616	const catalog = useCatalogRows();
@@ -555,10 +637,24 @@ export function AdminUsersPage() { · 20 unmodified lines
555	</div>	637	</div>
556	);	638	);
557		639
		640	const searching = search.term !== "";
		641
558	return (	642	return (
559	<PageContainer>	643	<PageContainer>
560	{header}	644	{header}
561		645
		646	<UserSearch
		647	value={search.typed}
		648	onChange={(value) => {
		649	search.setTyped(value);
		650	setOffset(0);
		651	}}
		652	onClear={() => {
		653	search.clear();
		654	setOffset(0);
		655	}}
		656	/>
		657
562	{isAsyncResultLoading(result)	658	{isAsyncResultLoading(result)
563	? loading	659	? loading
564	: AsyncResult.match(result, {	660	: AsyncResult.match(result, {
@@ -572,6 +668,25 @@ export function AdminUsersPage() { · 7 unmodified lines
572	onSuccess: ({ value }) => {	668	onSuccess: ({ value }) => {
573	const { rows, hasNext } = splitPage(value.users, ADMIN_USERS_PAGE_SIZE);	669	const { rows, hasNext } = splitPage(value.users, ADMIN_USERS_PAGE_SIZE);
574		670
		671	if (rows.length === 0 && searching && offset === 0) {
		672	return (
		673	<div
		674	className="rounded-lg border border-dashed border-border bg-card p-8"
		675	data-slot="admin-users-no-match"
		676	>
		677	<h2 className="text-base font-semibold text-foreground">No users match</h2>
		678	<p className="mt-2 max-w-xl text-sm leading-6 text-muted-foreground">
		679	Nobody in this workspace has a name or email containing “
		680	{search.term}”. Only people who have reached the workspace or connected
		681	an account are listed.
		682	</p>
		683	<Button variant="outline" size="sm" className="mt-4" onClick={search.clear}>
		684	Clear search
		685	</Button>
		686	</div>
		687	);
		688	}
		689
575	if (rows.length === 0) {	690	if (rows.length === 0) {
576	return (	691	return (
577	<div className="rounded-lg border border-dashed border-border bg-card p-8">	692	<div className="rounded-lg border border-dashed border-border bg-card p-8">

packages/react/src/pages/org.tsx+23−13

 type MemberData = {
   id: string;
-  email: string;
+  email: string | null;
   name: string | null;
   avatarUrl: string | null;
   role: string;
 type RoleData = { slug: string; name: string };
+/** What a member row is called: name, else email, else the one thing every
+ *  member has — a membership id — so a profile the host has not learned yet
+ *  still renders as a row an admin can act on. */
+const memberLabel = (member: MemberData): string => member.name ?? member.email ?? member.id;
+const memberInitials = (member: MemberData): string => {
+  if (member.name) {
+    return member.name
+      .split(" ")
+      .map((n: string) => n[0])
+      .join("")
+      .slice(0, 2)
+      .toUpperCase();
+  }
+  return (member.email?.[0] ?? "?").toUpperCase();
+};
 type InviteState = {
   email: string;
   roleSlug: string;
               const filtered = search
                 ? members.filter(
                     (m: MemberData) =>
-                      m.email.toLowerCase().includes(search.toLowerCase()) ||
+                      (m.email?.toLowerCase().includes(search.toLowerCase()) ?? false) ||
                       (m.name?.toLowerCase().includes(search.toLowerCase()) ?? false),
                   )
                 : members;
                         <img src={member.avatarUrl} alt="" className="size-8 rounded-full" />
                       ) : (
                         <div className="flex size-8 items-center justify-center rounded-full bg-muted text-xs font-semibold text-muted-foreground">
-                          {member.name
+                          {memberInitials(member)}
-                            ? member.name
-                                .split(" ")
-                                .map((n: string) => n[0])
-                                .join("")
-                                .slice(0, 2)
-                                .toUpperCase()
-                            : member.email[0]!.toUpperCase()}
                         </div>
                       )}
                       <div className="min-w-0">
                         <div className="flex items-center gap-2">
                           <p className="truncate text-sm font-medium text-foreground leading-none">
-                            {member.name ?? member.email}
+                            {memberLabel(member)}
                           </p>
                           {member.isCurrentUser && (
                             <Badge className="bg-muted text-muted-foreground">You</Badge>
                             <Badge className="bg-muted text-muted-foreground">Invited</Badge>
                           )}
                         </div>
-                        {member.name && (
+                        {member.name && member.email && (
                           <p className="mt-0.5 truncate text-xs text-muted-foreground leading-none">
                             {member.email}
                           </p>
                               onClick={() =>
                                 setRemovingMember({
                                   id: member.id,
-                                  name: member.name ?? member.email,
+                                  name: memberLabel(member),
                                 })
                               }
                             >