@stigmer/server 3.15.2 → 3.15.3-dev.20260914100347

package/src/domain/identityaccount/__tests__/provisioning.test.ts

@@ -18,6 +18,11 @@
  *      provisioning slot fire for both); a first-login race resolves the
  *      winner by subject whatever the failure's shape.
  *
+ * The answer says whether THIS call created the row (`created`; 20260913.01
+ * slice 4): the early return and the race loser answer false, so a rule
+ * keyed on first provisioning (the membership rules) runs exactly once per
+ * account and never on the idempotent path.
+ *
  * Step 4 of the cloud's flow (the personal organization) is not core: it
  * fires on `identity-account-provision:post-persist` in the composition.
  */
@@ -126,7 +131,9 @@ describe("provisionDirectAccount", () => {
       oidcCaller("auth0|alice"),
     );
 
-    expect(second).toEqual(first);
+    expect(second.account).toEqual(first.account);
+    expect(first.created, "the first call created the row").toBe(true);
+    expect(second.created, "the second call found it").toBe(false);
     expect(path.calls).toHaveLength(1);
     expect(userInfo.tokens).toEqual(["token-for-auth0|alice"]);
   });
@@ -140,7 +147,7 @@ describe("provisionDirectAccount", () => {
       createAccount: path.createAccount,
       userInfo,
     });
-    const account = await provisioner.provisionDirectAccount(
+    const { account } = await provisioner.provisionDirectAccount(
       "auth0|alice",
       oidcCaller("auth0|alice"),
     );
@@ -186,7 +193,7 @@ describe("provisionDirectAccount", () => {
       createAccount: path.createAccount,
       userInfo,
     });
-    const account = await provisioner.provisionDirectAccount(
+    const { account } = await provisioner.provisionDirectAccount(
       "local|operator@example.com",
       operatorCaller,
     );
@@ -205,7 +212,7 @@ describe("provisionDirectAccount", () => {
       createAccount: path.createAccount,
       userInfo: fakeUserInfo({ ...PROFILE, email: "" }),
     });
-    const account = await provisioner.provisionDirectAccount(
+    const { account } = await provisioner.provisionDirectAccount(
       "abc123@clients",
       oidcCaller("abc123@clients"),
     );
@@ -233,7 +240,8 @@ describe("provisionDirectAccount", () => {
       "auth0|carol",
       oidcCaller("auth0|carol"),
     );
-    expect(resolved).toEqual(winner);
+    expect(resolved.account).toEqual(winner);
+    expect(resolved.created, "the loser did not create the row").toBe(false);
     expect(accounts.rows.size).toBe(1);
   });
 
@@ -274,8 +282,12 @@ describe("provisionDirectAccount", () => {
       ),
     ]);
 
-    expect(a.metadata?.id).toBe(accountIdFor("auth0|erin"));
-    expect(b.metadata?.id).toBe(a.metadata?.id);
+    expect(a.account.metadata?.id).toBe(accountIdFor("auth0|erin"));
+    expect(b.account.metadata?.id).toBe(a.account.metadata?.id);
     expect(accounts.rows.size).toBe(1);
+    expect(
+      [a.created, b.created].filter(Boolean),
+      "exactly one of the two created the row",
+    ).toHaveLength(1);
   });
 });

package/src/domain/identityaccount/__tests__/resolve.test.ts

@@ -16,6 +16,20 @@
  *   - a hit whose row carries no id is an infrastructure fault naming the
  *     subject, never a `""` principal — the one deliberate divergence
  *     from the cloud's inline `?? ""`.
+ *
+ * And the read in the other direction, `accountForCaller` (20260913.01
+ * slice 4, Q-S4-1): the account a CallerIdentity stands for, the two
+ * primary-key reads whoAmI has always made, stated once so the built-in
+ * role lifecycle and whoAmI cannot disagree:
+ *
+ *   - an identityId that IS an account id resolves by that id (the
+ *     verifier already re-stamped);
+ *   - otherwise the caller's subject (idpIdOf) resolves through the direct
+ *     lookup — the trusted-local operator's `local|<email>` and a
+ *     composition verifier that stamps the raw subject both land here;
+ *   - a caller whose credential names no subject (an opaque token) is
+ *     `undefined` with NO second read — the store is never asked about "";
+ *   - an idp-shaped caller with no account is `undefined`.
  */
 import { create } from "@bufbuild/protobuf";
 import { ConnectError } from "@connectrpc/connect";
@@ -24,8 +38,9 @@ import { describe, expect, it, vi } from "vitest";
 import { IdentityAccountSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
 import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
 
-import { accountIdFor } from "../constants.js";
-import { identityIdForSubject } from "../resolve.js";
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import { accountIdFor, localIdpIdFor } from "../constants.js";
+import { accountForCaller, identityIdForSubject } from "../resolve.js";
 import type { AccountsBySubject } from "../resolve.js";
 import { fakeIdentityAccountStore } from "./support.js";
 
@@ -112,3 +127,99 @@ describe("identityIdForSubject", () => {
     expect(String(error)).toContain("auth0|corrupt");
   });
 });
+
+/** An unsigned JWT-shaped token whose payload carries `sub` — what idpIdOf reads. */
+function tokenFor(sub: string): string {
+  const segment = (value: unknown): string =>
+    Buffer.from(JSON.stringify(value)).toString("base64url");
+  return `${segment({ alg: "none" })}.${segment({ sub })}.unsigned`;
+}
+
+function caller(overrides: Partial<CallerIdentity>): CallerIdentity {
+  return {
+    identityId: "",
+    callerClass: "user",
+    issuer: "",
+    rawToken: "",
+    ...overrides,
+  };
+}
+
+describe("accountForCaller — the account a caller stands for", () => {
+  it("an identityId that is an account id resolves by that id, with no subject read", async () => {
+    const accounts = seeded("auth0|known");
+    const bySubject = vi.spyOn(accounts, "findDirectByIdpId");
+
+    const account = await accountForCaller(
+      accounts,
+      caller({
+        identityId: accountIdFor("auth0|known"),
+        issuer: "https://issuer.test",
+        rawToken: tokenFor("auth0|known"),
+      }),
+    );
+
+    expect(account?.metadata?.id).toBe(accountIdFor("auth0|known"));
+    expect(bySubject).not.toHaveBeenCalled();
+  });
+
+  it("a raw-subject identityId resolves through the token's sub — the composition-verifier shape", async () => {
+    const accounts = seeded("auth0|raw");
+
+    const account = await accountForCaller(
+      accounts,
+      caller({
+        identityId: "auth0|raw",
+        issuer: "",
+        rawToken: tokenFor("auth0|raw"),
+      }),
+    );
+
+    expect(account?.metadata?.id).toBe(accountIdFor("auth0|raw"));
+  });
+
+  it("the trusted-local operator resolves through local|<identityId>", async () => {
+    const accounts = seeded(localIdpIdFor("operator@example.com"));
+
+    const account = await accountForCaller(
+      accounts,
+      caller({ identityId: "operator@example.com" }),
+    );
+
+    expect(account?.metadata?.id).toBe(
+      accountIdFor(localIdpIdFor("operator@example.com")),
+    );
+  });
+
+  it("a credential naming no subject is undefined and the store is never asked about ''", async () => {
+    const accounts = seeded("auth0|someone");
+    const bySubject = vi.spyOn(accounts, "findDirectByIdpId");
+
+    const account = await accountForCaller(
+      accounts,
+      caller({
+        identityId: "opaque",
+        issuer: "https://issuer.test",
+        rawToken: "not-a-jwt",
+      }),
+    );
+
+    expect(account).toBeUndefined();
+    expect(bySubject).not.toHaveBeenCalled();
+  });
+
+  it("an idp-shaped caller with no account is undefined", async () => {
+    const accounts = seeded("auth0|someone-else");
+
+    const account = await accountForCaller(
+      accounts,
+      caller({
+        identityId: "auth0|stranger",
+        issuer: "https://issuer.test",
+        rawToken: tokenFor("auth0|stranger"),
+      }),
+    );
+
+    expect(account).toBeUndefined();
+  });
+});

package/src/domain/identityaccount/constants.ts

@@ -5,17 +5,20 @@
  *
  * The derived id (A1). A direct account's id is a pure function of its
  * subject: `ida_` + the top 130 bits of sha256(idp_id) as 26 lowercase
- * Crockford-base32 characters. The shape is indistinguishable from a
- * minted `{prefix}_{ulid}`, so nothing downstream learns a second id
- * grammar, and the PRIMARY KEY becomes the one home of "one account per
- * subject": the generic store has no secondary uniqueness and its save is
- * an upsert (`store/sqlite/store.ts`), so a lookup-then-insert on a scan
- * could never close the first-login race. Two replicas deriving the same
- * id converge by primary key with no migration and no second copy of any
- * field. The hash is one-way, so an issuer subject never leaks into the
- * `created_by.id` stamps that ride on every resource. The golden vectors in
- * __tests__/constants.test.ts are wire-adjacent contract: a change here
- * re-addresses every direct account open source ever created.
+ * Crockford-base32 characters, through `derivedId` in
+ * pipeline/steps/defaults.ts (the one encoder every derived kind shares
+ * since 20260913.01 slice 2; the IamPolicy id is the other). The shape is
+ * indistinguishable from a minted `{prefix}_{ulid}`, so nothing downstream
+ * learns a second id grammar, and the PRIMARY KEY becomes the one home of
+ * "one account per subject": the generic store has no secondary uniqueness
+ * and its save is an upsert (`store/sqlite/store.ts`), so a
+ * lookup-then-insert on a scan could never close the first-login race. Two
+ * replicas deriving the same id converge by primary key with no migration
+ * and no second copy of any field. The hash is one-way, so an issuer
+ * subject never leaks into the `created_by.id` stamps that ride on every
+ * resource. The golden vectors in __tests__/constants.test.ts are
+ * wire-adjacent contract: a change here re-addresses every direct account
+ * open source ever created.
  *
  * `idpIdOf` (A2) is the ONE place a CallerIdentity becomes a subject. An
  * issuer-vouched token is read for its `sub` (already verified at
@@ -28,19 +31,12 @@
  * The copy moved from the cloud's iam/account/handlers.ts as-is: the CLI,
  * console and SDK show these sentences verbatim, so they are contract.
  */
-import { createHash } from "node:crypto";
-
 import type { CallerIdentity } from "../../extensions/identity.js";
+import { derivedId } from "../../pipeline/steps/defaults.js";
 
 /** The kind's id prefix (kind_meta `identity_account.id_prefix`). */
 export const ACCOUNT_ID_PREFIX = "ida";
 
-/** Crockford base32, lowercased — the alphabet every minted ULID id uses. */
-const CROCKFORD_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
-const DERIVED_ID_CHARS = 26;
-const DERIVED_ID_BITS = BigInt(DERIVED_ID_CHARS * 5);
-const SHA256_BITS = 256n;
-
 /**
  * The derived account id of a direct account with subject `idpId`. Pure,
  * total over non-empty input; an empty subject has no principal and so
@@ -50,18 +46,7 @@ export function accountIdFor(idpId: string): string {
   if (idpId === "") {
     throw new Error("idp_id must not be empty");
   }
-  const digest = createHash("sha256").update(idpId, "utf8").digest();
-  let bits = 0n;
-  for (const byte of digest) {
-    bits = (bits << 8n) | BigInt(byte);
-  }
-  let top = bits >> (SHA256_BITS - DERIVED_ID_BITS);
-  let encoded = "";
-  for (let i = 0; i < DERIVED_ID_CHARS; i++) {
-    encoded = CROCKFORD_ALPHABET[Number(top & 31n)] + encoded;
-    top >>= 5n;
-  }
-  return `${ACCOUNT_ID_PREFIX}_${encoded}`;
+  return derivedId(ACCOUNT_ID_PREFIX, idpId);
 }
 
 /**

package/src/domain/identityaccount/controller.ts

@@ -27,13 +27,16 @@
  * ensure runs it as the trusted-local user.
  *
  * Direct handlers (no pipeline): whoAmI (the cloud's two primary-key
- * reads through idpIdOf; NOT_FOUND for the unprovisioned), getByEmail and
- * getByIdpId (lookup FIRST, then authorizeDirect on the FOUND id — the
- * cloud's order; the annotation's `field_path = "value"` would otherwise
- * hand the Authorizer an email as a resource id), getActorInfo, and
- * provisionMyAccount (the provisioner, then the composed post-persist
- * gates; UNAUTHENTICATED with the cloud's copy for a credential naming no
- * subject; UNAVAILABLE with the cloud's copy when userinfo fails).
+ * reads, stated once as resolve.ts accountForCaller; NOT_FOUND for the
+ * unprovisioned), getByEmail and getByIdpId (lookup FIRST, then
+ * authorizeDirect on the FOUND id — the cloud's order; the annotation's
+ * `field_path = "value"` would otherwise hand the Authorizer an email as a
+ * resource id), getActorInfo, and provisionMyAccount (the provisioner,
+ * then — on the call that CREATED the row — the core AccountCreatedHook
+ * (open source's membership rules, 20260913.01 slice 4), then the composed
+ * post-persist gates; UNAUTHENTICATED with the cloud's copy for a
+ * credential naming no subject; UNAVAILABLE with the cloud's copy when
+ * userinfo fails).
  *
  * The four federation RPCs refuse UNIMPLEMENTED with the edition reason
  * when no unit composes the capability (never INTERNAL; the organization
@@ -69,6 +72,7 @@ import type { Logger } from "../../boot/logger.js";
 import type { Authorizer } from "../../extensions/authorizer.js";
 import { stepsForSlot } from "../../extensions/gate-slots.js";
 import type { ResolvedGateSteps } from "../../extensions/gate-slots.js";
+import { isPlatformPipelineCaller } from "../../extensions/identity.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
 import type { IdentityFederation } from "../../extensions/identity-federation.js";
 import type { ResourceAuthorizationLifecycle } from "../../extensions/resource-authorization.js";
@@ -102,11 +106,13 @@ import {
   idpIdOf,
 } from "./constants.js";
 import type {
+  AccountCreatedHook,
   CreateAccount,
   CreateAccountInput,
   DirectAccountProvisioner,
 } from "./provisioning.js";
 import { UserInfoFetchError } from "./provisioning.js";
+import { accountForCaller } from "./resolve.js";
 import {
   accountNotFoundError,
   newAssignBackendFieldsStep,
@@ -140,6 +146,13 @@ export interface IdentityAccountControllerDeps extends CreateAccountPathDeps {
   readonly federation: IdentityFederation | undefined;
   /** The composed slot registrations — this domain's provision slot (Q-IA-9, A10). */
   readonly gateSteps: ResolvedGateSteps;
+  /**
+   * The core first-provisioning rule — open source's membership rules
+   * under the built-in authorization posture; undefined when a
+   * composition brings its own Authorizer and so its own onboarding
+   * (20260913.01, Q-OR-6).
+   */
+  readonly membership: AccountCreatedHook | undefined;
 }
 
 /** Registers both identityaccount services on the router (routes stage). */
@@ -294,11 +307,9 @@ function createRpc(
 }
 
 function guardInternalRpc(caller: CallerIdentity): void {
-  if (
-    caller.callerClass === "machine" ||
-    caller.callerClass === "internal" ||
-    caller.origin === "in-process"
-  ) {
+  // The one definition of "the platform's own pipelines"
+  // (extensions/identity.ts), shared with the IamPolicy system RPCs.
+  if (isPlatformPipelineCaller(caller)) {
     return;
   }
   throw new ConnectError(CREATE_IS_INTERNAL_MESSAGE, Code.PermissionDenied);
@@ -458,16 +469,12 @@ async function whoAmI(
   ctx: HandlerContext,
 ): Promise<IdentityAccount> {
   const caller = callerIdentityOf(ctx);
-  let account = await read(
-    () => deps.accounts.findById(caller.identityId),
+  // The domain's one statement of "the caller's account" (resolve.ts):
+  // by id, then by subject — shared with the built-in role lifecycle.
+  const account = await read(
+    () => accountForCaller(deps.accounts, caller),
     "failed to load identity account",
   );
-  if (account === undefined) {
-    account = await read(
-      () => deps.accounts.findDirectByIdpId(idpIdOf(caller)),
-      "failed to load identity account",
-    );
-  }
   if (account === undefined) {
     throw new ConnectError(ACCOUNT_NOT_FOUND_FOR_CALLER_MESSAGE, Code.NotFound);
   }
@@ -530,16 +537,28 @@ async function lookupThenAuthorize(
 
 /**
  * provisionMyAccount — the subject from the caller's credential, the
- * provisioner's flow, then the composed post-persist gates (the cloud's
- * personal organization) with the caller RE-STAMPED as the account: the
- * position-1 identity was idp-shaped because no row existed when the
- * verifier ran, and a gate that attributes ownership must name the
- * account, never a principal no later request carries. The gates run on
- * EVERY call, the idempotent early return included — the cloud's step
- * backfills accounts that predate personal organizations there, which is
- * why Q-IA-9 chose a slot over onResourceCreated. Non-transactional in
- * the `org-create:post-persist` sense: a gate failure fails the request,
- * the row survives, the next call heals it.
+ * provisioner's flow, then two post-persist consumers with the caller
+ * RE-STAMPED as the account: the position-1 identity was idp-shaped
+ * because no row existed when the verifier ran, and anything that
+ * attributes ownership must name the account, never a principal no later
+ * request carries.
+ *
+ *   1. The core AccountCreatedHook (open source's membership rules), on
+ *      the call that CREATED the row only (`created`): the slot below
+ *      fires on the idempotent path by design, and a rule keyed on "holds
+ *      no row" there would re-admit a member an administrator had just
+ *      revoked (20260913.01 plan finding 2). A throw fails the request
+ *      INTERNAL with the row in place and the rule does not run again for
+ *      that account — the ratified store-fault mapping, and the one loud
+ *      record of the window slice 4's Q-S4-4 accepted: the rule's writes
+ *      are idempotent, so a partial run is harmless, and the recovery is
+ *      an administrator's grant.
+ *   2. The composed post-persist gates (the cloud's personal
+ *      organization), on EVERY call — the cloud's step backfills accounts
+ *      that predate personal organizations there, which is why Q-IA-9
+ *      chose a slot over onResourceCreated. Non-transactional in the
+ *      `org-create:post-persist` sense: a gate failure fails the request,
+ *      the row survives, the next call heals it.
  */
 async function provisionMyAccount(
   deps: IdentityAccountControllerDeps,
@@ -552,8 +571,12 @@ async function provisionMyAccount(
     throw new ConnectError(NO_IDP_ID_MESSAGE, Code.Unauthenticated);
   }
   let account: IdentityAccount;
+  let created: boolean;
   try {
-    account = await deps.provisioner.provisionDirectAccount(idpId, caller);
+    ({ account, created } = await deps.provisioner.provisionDirectAccount(
+      idpId,
+      caller,
+    ));
   } catch (error) {
     if (error instanceof UserInfoFetchError) {
       throw new ConnectError(
@@ -563,6 +586,17 @@ async function provisionMyAccount(
     }
     throw error;
   }
+  const asAccount: CallerIdentity = {
+    ...caller,
+    identityId: account.metadata?.id ?? "",
+  };
+  if (created && deps.membership !== undefined) {
+    try {
+      await deps.membership.onAccountCreated(account, asAccount);
+    } catch (error) {
+      throw internalError(error, "failed to record organization membership");
+    }
+  }
   // The ratified provision slot (Q-IA-9; the gate-slots.ts header carries
   // its semantics). Empty in OSS — no pipeline is built for zero steps.
   const gates = stepsForSlot<typeof IdentityAccountSchema>(
@@ -570,10 +604,6 @@ async function provisionMyAccount(
     "identity-account-provision:post-persist",
   );
   if (gates.length > 0) {
-    const asAccount: CallerIdentity = {
-      ...caller,
-      identityId: account.metadata?.id ?? "",
-    };
     const reqCtx = new RequestContext(
       IdentityAccountSchema,
       account,

package/src/domain/identityaccount/operator.ts

@@ -34,7 +34,10 @@ import { create } from "@bufbuild/protobuf";
 import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
 import { IdentityAccountSpecSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
 
-import { trustedLocalIdentityFor } from "../../pipeline/interceptors/auth.js";
+import {
+  SYSTEM_OPERATOR_IDENTITY_ID,
+  trustedLocalIdentityFor,
+} from "../../pipeline/interceptors/auth.js";
 import { accountIdFor, localIdpIdFor } from "./constants.js";
 import type { CreateAccount } from "./provisioning.js";
 import { resolveCreateRace } from "./provisioning.js";
@@ -52,9 +55,6 @@ export interface OperatorAccountDeps {
   readonly createAccount: CreateAccount;
 }
 
-/** The unconfigured laptop's operator: what the interceptor stamps as identityId. */
-const SYSTEM_OPERATOR = "system";
-
 export async function ensureOperatorAccount(
   deps: OperatorAccountDeps,
   operator: OperatorIdentity,
@@ -72,7 +72,7 @@ export async function ensureOperatorAccount(
       ? operator.displayName
       : operator.email !== ""
         ? operator.email
-        : SYSTEM_OPERATOR;
+        : SYSTEM_OPERATOR_IDENTITY_ID;
   try {
     return await deps.createAccount(
       {

package/src/domain/identityaccount/provisioning.ts

@@ -28,6 +28,16 @@
  * fires on the `identity-account-provision:post-persist` slot in the
  * composition (A10), wired by the controller.
  *
+ * The answer says whether THIS call created the row (`ProvisionedAccount.
+ * created`; 20260913.01 slice 4): the idempotent early return and the
+ * race loser answer false. The slot above fires on every call by design
+ * (the cloud's backfill needs that), so a CORE rule that must run exactly
+ * once per person — the open-source membership rules, which hand out
+ * organization roles at first sign-in — keys on `created` instead, through
+ * the AccountCreatedHook this domain offers and the controller runs. The
+ * hook is declared here, in the domain that fires it, so the domain that
+ * implements it (iampolicy) depends on this one and never the reverse.
+ *
  * This module holds the domain flow over two PORTS — the store and the
  * userinfo client — and no network code; identity/oidc-userinfo.ts is the
  * OIDC implementation the composition root wires in.
@@ -88,22 +98,46 @@ export interface DirectAccountProvisionerDeps {
   readonly userInfo: UserInfoClient;
 }
 
+/** The provisioner's answer: the account, and whether this call created its row. */
+export interface ProvisionedAccount {
+  readonly account: IdentityAccount;
+  /** False on the idempotent early return and for a first-login race's loser. */
+  readonly created: boolean;
+}
+
+/**
+ * What the identity-account domain offers a core rule keyed on a person's
+ * FIRST provisioning (the open-source membership rules,
+ * domain/iampolicy/membership.ts). Runs once per account, on the call
+ * whose `created` is true, with the caller RE-STAMPED as the account, so
+ * whatever the hook writes attributes to the account and never to the
+ * idp-shaped principal the verifier admitted before the row existed. Its
+ * failure semantics are the controller's: a throw fails the request with
+ * the account in place, and the hook does not run again for that account.
+ */
+export interface AccountCreatedHook {
+  onAccountCreated(
+    account: IdentityAccount,
+    caller: CallerIdentity,
+  ): Promise<void>;
+}
+
 export interface DirectAccountProvisioner {
   /** provisionMyAccount's domain flow; `idpId` is the caller's verified subject. */
   provisionDirectAccount(
     idpId: string,
     caller: CallerIdentity,
-  ): Promise<IdentityAccount>;
+  ): Promise<ProvisionedAccount>;
 }
 
 export function newDirectAccountProvisioner(
   deps: DirectAccountProvisionerDeps,
 ): DirectAccountProvisioner {
   return {
-    async provisionDirectAccount(idpId, caller): Promise<IdentityAccount> {
+    async provisionDirectAccount(idpId, caller): Promise<ProvisionedAccount> {
       const existing = await deps.accounts.findDirectByIdpId(idpId);
       if (existing !== undefined) {
-        return existing;
+        return { account: existing, created: false };
       }
 
       const profile = await profileOf(deps.userInfo, caller);
@@ -121,11 +155,15 @@ export function newDirectAccountProvisioner(
       };
 
       try {
-        return await deps.createAccount(input, caller);
+        return {
+          account: await deps.createAccount(input, caller),
+          created: true,
+        };
       } catch (error) {
-        return resolveCreateRace(error, () =>
+        const winner = await resolveCreateRace(error, () =>
           deps.accounts.findDirectByIdpId(idpId),
         );
+        return { account: winner, created: false };
       }
     },
   };

package/src/domain/identityaccount/resolve.ts

@@ -28,12 +28,35 @@
  * no id is the one deliberate divergence from the cloud's inline
  * `metadata?.id ?? ""`: a `""` principal is the silent-junk failure the
  * oss#405 doctrine forbids, so it is a loud fault naming the subject.
+ *
+ * The same knowledge read in the caller's direction is `accountForCaller`
+ * (20260913.01 slice 4, Q-S4-1): the account a stamped CallerIdentity
+ * stands for. Two primary-key reads, the cloud's whoAmI order — the
+ * identityId AS an account id (a verifier that resolved), then the
+ * caller's subject through the direct lookup (a verifier that did not:
+ * the trusted-local interceptor, which stamps the operator's email and
+ * never consults the store; a composition verifier that runs before any
+ * row exists). It lives here so whoAmI and the built-in role lifecycle,
+ * which asks "whose organization is this" from the creating caller,
+ * cannot answer the same question two ways. A credential naming no
+ * subject is `undefined` with no second read: the store is never asked
+ * about "".
  */
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { idpIdOf } from "./constants.js";
 import type { IdentityAccountStore } from "./store.js";
 
 /** The one read a verifier needs from the domain: the direct account for a subject. */
 export type AccountsBySubject = Pick<IdentityAccountStore, "findDirectByIdpId">;
 
+/** The two reads the caller-direction resolution needs: by id, then by subject. */
+export type AccountsByCaller = Pick<
+  IdentityAccountStore,
+  "findById" | "findDirectByIdpId"
+>;
+
 export async function identityIdForSubject(
   accounts: AccountsBySubject,
   subject: string,
@@ -50,3 +73,23 @@ export async function identityIdForSubject(
   }
   return id;
 }
+
+/**
+ * The account `caller` stands for, or `undefined` when there is none (an
+ * idp-shaped caller before provisioning; a credential naming no subject).
+ * Faults propagate as they are — the caller decides the wire shape.
+ */
+export async function accountForCaller(
+  accounts: AccountsByCaller,
+  caller: CallerIdentity,
+): Promise<IdentityAccount | undefined> {
+  const byId = await accounts.findById(caller.identityId);
+  if (byId !== undefined) {
+    return byId;
+  }
+  const subject = idpIdOf(caller);
+  if (subject === "") {
+    return undefined;
+  }
+  return accounts.findDirectByIdpId(subject);
+}