Add ResolveLinkedAccountByUsername to UsersService

Callers that only know how a person is addressed in chat cannot use the
id-based lookup. Same fail-closed identity rule: an ambiguous username
fails rather than resolving to a guessed user, because acting on the wrong
one can mean phoning someone who never asked to be called.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

users.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go. DO NOT EDIT.
 // versions:
 // 	protoc-gen-go v1.36.11
-// 	protoc        v7.34.2
+// 	protoc        (unknown)
 // source: users.proto
 
 package proto
@@ -763,6 +763,60 @@ func (x *ResolveLinkedAccountRequest) GetAccountId() string {
 	return ""
 }
 
+type ResolveLinkedAccountByUsernameRequest struct {
+	state    protoimpl.MessageState `protogen:"open.v1"`
+	Platform string                 `protobuf:"bytes,1,opt,name=platform,proto3" json:"platform,omitempty"`
+	// Username without a leading "@"; matched case-insensitively, the way
+	// people write it in chat.
+	Username      string `protobuf:"bytes,2,opt,name=username,proto3" json:"username,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) Reset() {
+	*x = ResolveLinkedAccountByUsernameRequest{}
+	mi := &file_users_proto_msgTypes[13]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ResolveLinkedAccountByUsernameRequest) ProtoMessage() {}
+
+func (x *ResolveLinkedAccountByUsernameRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[13]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ResolveLinkedAccountByUsernameRequest.ProtoReflect.Descriptor instead.
+func (*ResolveLinkedAccountByUsernameRequest) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{13}
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) GetPlatform() string {
+	if x != nil {
+		return x.Platform
+	}
+	return ""
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) GetUsername() string {
+	if x != nil {
+		return x.Username
+	}
+	return ""
+}
+
 type ResolveLinkedAccountResponse struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
 	Linked        bool                   `protobuf:"varint,1,opt,name=linked,proto3" json:"linked,omitempty"`
@@ -774,7 +828,7 @@ type ResolveLinkedAccountResponse struct {
 
 func (x *ResolveLinkedAccountResponse) Reset() {
 	*x = ResolveLinkedAccountResponse{}
-	mi := &file_users_proto_msgTypes[13]
+	mi := &file_users_proto_msgTypes[14]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -786,7 +840,7 @@ func (x *ResolveLinkedAccountResponse) String() string {
 func (*ResolveLinkedAccountResponse) ProtoMessage() {}
 
 func (x *ResolveLinkedAccountResponse) ProtoReflect() protoreflect.Message {
-	mi := &file_users_proto_msgTypes[13]
+	mi := &file_users_proto_msgTypes[14]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -799,7 +853,7 @@ func (x *ResolveLinkedAccountResponse) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ResolveLinkedAccountResponse.ProtoReflect.Descriptor instead.
 func (*ResolveLinkedAccountResponse) Descriptor() ([]byte, []int) {
-	return file_users_proto_rawDescGZIP(), []int{13}
+	return file_users_proto_rawDescGZIP(), []int{14}
 }
 
 func (x *ResolveLinkedAccountResponse) GetLinked() bool {
@@ -884,11 +938,14 @@ const file_users_proto_rawDesc = "" +
 	"\x1bResolveLinkedAccountRequest\x12\x1a\n" +
 	"\bplatform\x18\x01 \x01(\tR\bplatform\x12\x1d\n" +
 	"\n" +
-	"account_id\x18\x02 \x01(\tR\taccountId\"\x7f\n" +
+	"account_id\x18\x02 \x01(\tR\taccountId\"_\n" +
+	"%ResolveLinkedAccountByUsernameRequest\x12\x1a\n" +
+	"\bplatform\x18\x01 \x01(\tR\bplatform\x12\x1a\n" +
+	"\busername\x18\x02 \x01(\tR\busername\"\x7f\n" +
 	"\x1cResolveLinkedAccountResponse\x12\x16\n" +
 	"\x06linked\x18\x01 \x01(\bR\x06linked\x12$\n" +
 	"\x0eglobal_user_id\x18\x02 \x01(\x03R\fglobalUserId\x12!\n" +
-	"\fdisplay_name\x18\x03 \x01(\tR\vdisplayName2\xca\x06\n" +
+	"\fdisplay_name\x18\x03 \x01(\tR\vdisplayName2\xbf\a\n" +
 	"\fUsersService\x12E\n" +
 	"\x10CreateGlobalUser\x12\x1e.users.CreateGlobalUserRequest\x1a\x11.users.GlobalUser\x12?\n" +
 	"\rGetGlobalUser\x12\x1b.users.GetGlobalUserRequest\x1a\x11.users.GlobalUser\x12M\n" +
@@ -899,7 +956,8 @@ const file_users_proto_rawDesc = "" +
 	"\x10GetLinkedAccount\x12\x1e.users.GetLinkedAccountRequest\x1a\x14.users.LinkedAccount\x12j\n" +
 	"\x1bGetLinkedAccountsByPlatform\x12).users.GetLinkedAccountsByPlatformRequest\x1a .users.GetLinkedAccountsResponse\x12x\n" +
 	"\"GetLinkedAccountsByUserAndPlatform\x120.users.GetLinkedAccountsByUserAndPlatformRequest\x1a .users.GetLinkedAccountsResponse\x12_\n" +
-	"\x14ResolveLinkedAccount\x12\".users.ResolveLinkedAccountRequest\x1a#.users.ResolveLinkedAccountResponseB,Z*git.be.kaien.ru/l-ai/l-ai-core-proto/protob\x06proto3"
+	"\x14ResolveLinkedAccount\x12\".users.ResolveLinkedAccountRequest\x1a#.users.ResolveLinkedAccountResponse\x12s\n" +
+	"\x1eResolveLinkedAccountByUsername\x12,.users.ResolveLinkedAccountByUsernameRequest\x1a#.users.ResolveLinkedAccountResponseB,Z*git.be.kaien.ru/l-ai/l-ai-core-proto/protob\x06proto3"
 
 var (
 	file_users_proto_rawDescOnce sync.Once
@@ -913,7 +971,7 @@ func file_users_proto_rawDescGZIP() []byte {
 	return file_users_proto_rawDescData
 }
 
-var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 14)
+var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 15)
 var file_users_proto_goTypes = []any{
 	(*GlobalUser)(nil),                                // 0: users.GlobalUser
 	(*LinkedAccount)(nil),                             // 1: users.LinkedAccount
@@ -928,21 +986,22 @@ var file_users_proto_goTypes = []any{
 	(*GetLinkedAccountsByUserAndPlatformRequest)(nil), // 10: users.GetLinkedAccountsByUserAndPlatformRequest
 	(*GetLinkedAccountsResponse)(nil),                 // 11: users.GetLinkedAccountsResponse
 	(*ResolveLinkedAccountRequest)(nil),               // 12: users.ResolveLinkedAccountRequest
-	(*ResolveLinkedAccountResponse)(nil),              // 13: users.ResolveLinkedAccountResponse
+	(*ResolveLinkedAccountByUsernameRequest)(nil),     // 13: users.ResolveLinkedAccountByUsernameRequest
-	(*timestamppb.Timestamp)(nil),                     // 14: google.protobuf.Timestamp
+	(*ResolveLinkedAccountResponse)(nil),              // 14: users.ResolveLinkedAccountResponse
-	(*emptypb.Empty)(nil),                             // 15: google.protobuf.Empty
+	(*timestamppb.Timestamp)(nil),                     // 15: google.protobuf.Timestamp
+	(*emptypb.Empty)(nil),                             // 16: google.protobuf.Empty
 }
 var file_users_proto_depIdxs = []int32{
-	14, // 0: users.GlobalUser.created_at:type_name -> google.protobuf.Timestamp
+	15, // 0: users.GlobalUser.created_at:type_name -> google.protobuf.Timestamp
-	14, // 1: users.GlobalUser.updated_at:type_name -> google.protobuf.Timestamp
+	15, // 1: users.GlobalUser.updated_at:type_name -> google.protobuf.Timestamp
 	1,  // 2: users.GlobalUser.linked_accounts:type_name -> users.LinkedAccount
-	14, // 3: users.LinkedAccount.linked_at:type_name -> google.protobuf.Timestamp
+	15, // 3: users.LinkedAccount.linked_at:type_name -> google.protobuf.Timestamp
-	14, // 4: users.LinkedAccount.updated_at:type_name -> google.protobuf.Timestamp
+	15, // 4: users.LinkedAccount.updated_at:type_name -> google.protobuf.Timestamp
 	0,  // 5: users.GetAllGlobalUsersResponse.users:type_name -> users.GlobalUser
 	1,  // 6: users.GetLinkedAccountsResponse.accounts:type_name -> users.LinkedAccount
 	2,  // 7: users.UsersService.CreateGlobalUser:input_type -> users.CreateGlobalUserRequest
 	3,  // 8: users.UsersService.GetGlobalUser:input_type -> users.GetGlobalUserRequest
-	15, // 9: users.UsersService.GetAllGlobalUsers:input_type -> google.protobuf.Empty
+	16, // 9: users.UsersService.GetAllGlobalUsers:input_type -> google.protobuf.Empty
 	5,  // 10: users.UsersService.UpdateDisplayName:input_type -> users.UpdateDisplayNameRequest
 	6,  // 11: users.UsersService.LinkAccount:input_type -> users.LinkAccountRequest
 	7,  // 12: users.UsersService.UnlinkAccount:input_type -> users.UnlinkAccountRequest
@@ -950,18 +1009,20 @@ var file_users_proto_depIdxs = []int32{
 	9,  // 14: users.UsersService.GetLinkedAccountsByPlatform:input_type -> users.GetLinkedAccountsByPlatformRequest
 	10, // 15: users.UsersService.GetLinkedAccountsByUserAndPlatform:input_type -> users.GetLinkedAccountsByUserAndPlatformRequest
 	12, // 16: users.UsersService.ResolveLinkedAccount:input_type -> users.ResolveLinkedAccountRequest
-	0,  // 17: users.UsersService.CreateGlobalUser:output_type -> users.GlobalUser
+	13, // 17: users.UsersService.ResolveLinkedAccountByUsername:input_type -> users.ResolveLinkedAccountByUsernameRequest
-	0,  // 18: users.UsersService.GetGlobalUser:output_type -> users.GlobalUser
+	0,  // 18: users.UsersService.CreateGlobalUser:output_type -> users.GlobalUser
-	4,  // 19: users.UsersService.GetAllGlobalUsers:output_type -> users.GetAllGlobalUsersResponse
+	0,  // 19: users.UsersService.GetGlobalUser:output_type -> users.GlobalUser
-	15, // 20: users.UsersService.UpdateDisplayName:output_type -> google.protobuf.Empty
+	4,  // 20: users.UsersService.GetAllGlobalUsers:output_type -> users.GetAllGlobalUsersResponse
-	1,  // 21: users.UsersService.LinkAccount:output_type -> users.LinkedAccount
+	16, // 21: users.UsersService.UpdateDisplayName:output_type -> google.protobuf.Empty
-	15, // 22: users.UsersService.UnlinkAccount:output_type -> google.protobuf.Empty
+	1,  // 22: users.UsersService.LinkAccount:output_type -> users.LinkedAccount
-	1,  // 23: users.UsersService.GetLinkedAccount:output_type -> users.LinkedAccount
+	16, // 23: users.UsersService.UnlinkAccount:output_type -> google.protobuf.Empty
-	11, // 24: users.UsersService.GetLinkedAccountsByPlatform:output_type -> users.GetLinkedAccountsResponse
+	1,  // 24: users.UsersService.GetLinkedAccount:output_type -> users.LinkedAccount
-	11, // 25: users.UsersService.GetLinkedAccountsByUserAndPlatform:output_type -> users.GetLinkedAccountsResponse
+	11, // 25: users.UsersService.GetLinkedAccountsByPlatform:output_type -> users.GetLinkedAccountsResponse
-	13, // 26: users.UsersService.ResolveLinkedAccount:output_type -> users.ResolveLinkedAccountResponse
+	11, // 26: users.UsersService.GetLinkedAccountsByUserAndPlatform:output_type -> users.GetLinkedAccountsResponse
-	17, // [17:27] is the sub-list for method output_type
+	14, // 27: users.UsersService.ResolveLinkedAccount:output_type -> users.ResolveLinkedAccountResponse
-	7,  // [7:17] is the sub-list for method input_type
+	14, // 28: users.UsersService.ResolveLinkedAccountByUsername:output_type -> users.ResolveLinkedAccountResponse
+	18, // [18:29] is the sub-list for method output_type
+	7,  // [7:18] is the sub-list for method input_type
 	7,  // [7:7] is the sub-list for extension type_name
 	7,  // [7:7] is the sub-list for extension extendee
 	0,  // [0:7] is the sub-list for field type_name
@@ -978,7 +1039,7 @@ func file_users_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_users_proto_rawDesc), len(file_users_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   14,
+			NumMessages:   15,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

users.proto

@@ -37,6 +37,20 @@ service UsersService {
   //     FailedPrecondition (ambiguous identity); callers must not persist
   //     anything under a guessed identity
   rpc ResolveLinkedAccount(ResolveLinkedAccountRequest) returns (ResolveLinkedAccountResponse);
+
+  // ResolveLinkedAccountByUsername resolves the global user owning a platform
+  // account addressed by its username rather than its id (e.g.
+  // platform="telegram", username="kaien"). Read-only: it never creates a
+  // global user or a linked account.
+  //
+  // Callers that only know how a person is addressed in chat need this; the
+  // id-based lookup above cannot serve them. Same fail-closed identity rule:
+  //   - no match                    -> found=false
+  //   - one global user             -> that user
+  //   - more than one global user   -> FailedPrecondition (ambiguous), so a
+  //     caller never acts on a guessed identity. Acting on the wrong one here
+  //     can mean phoning a person who never asked to be called.
+  rpc ResolveLinkedAccountByUsername(ResolveLinkedAccountByUsernameRequest) returns (ResolveLinkedAccountResponse);
 }
 
 message GlobalUser {
@@ -112,6 +126,13 @@ message ResolveLinkedAccountRequest {
   string account_id = 2;
 }
 
+message ResolveLinkedAccountByUsernameRequest {
+  string platform = 1;
+  // Username without a leading "@"; matched case-insensitively, the way
+  // people write it in chat.
+  string username = 2;
+}
+
 message ResolveLinkedAccountResponse {
   bool linked = 1;
   int64 global_user_id = 2;

users_grpc.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
-// - protoc-gen-go-grpc v1.6.1
+// - protoc-gen-go-grpc v1.6.2
-// - protoc             v7.34.2
+// - protoc             (unknown)
 // source: users.proto
 
 package proto
@@ -30,6 +30,7 @@ const (
 	UsersService_GetLinkedAccountsByPlatform_FullMethodName        = "/users.UsersService/GetLinkedAccountsByPlatform"
 	UsersService_GetLinkedAccountsByUserAndPlatform_FullMethodName = "/users.UsersService/GetLinkedAccountsByUserAndPlatform"
 	UsersService_ResolveLinkedAccount_FullMethodName               = "/users.UsersService/ResolveLinkedAccount"
+	UsersService_ResolveLinkedAccountByUsername_FullMethodName     = "/users.UsersService/ResolveLinkedAccountByUsername"
 )
 
 // UsersServiceClient is the client API for UsersService service.
@@ -54,10 +55,29 @@ type UsersServiceClient interface {
 	// identity to the stable global_user_id. It NEVER creates a global user or
 	// a linked account.
 	//
-	// linked=false means the account is not linked to any global user. When
+	// Identity boundary invariant: (platform, account_id) -> at most one
-	// several links exist for the same account (legacy duplicates), the oldest
+	// canonical global_user_id.
-	// (smallest linked_account id) wins — deterministic across retries.
+	//   - no rows            -> linked=false (account not linked; nothing created)
+	//   - one distinct global user -> that user; if several legacy link rows
+	//     exist for the SAME user, the oldest (smallest linked_account id) wins,
+	//     deterministic across retries
+	//   - more than one distinct global user -> FAILS CLOSED with
+	//     FailedPrecondition (ambiguous identity); callers must not persist
+	//     anything under a guessed identity
 	ResolveLinkedAccount(ctx context.Context, in *ResolveLinkedAccountRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error)
+	// ResolveLinkedAccountByUsername resolves the global user owning a platform
+	// account addressed by its username rather than its id (e.g.
+	// platform="telegram", username="kaien"). Read-only: it never creates a
+	// global user or a linked account.
+	//
+	// Callers that only know how a person is addressed in chat need this; the
+	// id-based lookup above cannot serve them. Same fail-closed identity rule:
+	//   - no match                    -> found=false
+	//   - one global user             -> that user
+	//   - more than one global user   -> FailedPrecondition (ambiguous), so a
+	//     caller never acts on a guessed identity. Acting on the wrong one here
+	//     can mean phoning a person who never asked to be called.
+	ResolveLinkedAccountByUsername(ctx context.Context, in *ResolveLinkedAccountByUsernameRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error)
 }
 
 type usersServiceClient struct {
@@ -168,6 +188,16 @@ func (c *usersServiceClient) ResolveLinkedAccount(ctx context.Context, in *Resol
 	return out, nil
 }
 
+func (c *usersServiceClient) ResolveLinkedAccountByUsername(ctx context.Context, in *ResolveLinkedAccountByUsernameRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(ResolveLinkedAccountResponse)
+	err := c.cc.Invoke(ctx, UsersService_ResolveLinkedAccountByUsername_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // UsersServiceServer is the server API for UsersService service.
 // All implementations must embed UnimplementedUsersServiceServer
 // for forward compatibility.
@@ -190,10 +220,29 @@ type UsersServiceServer interface {
 	// identity to the stable global_user_id. It NEVER creates a global user or
 	// a linked account.
 	//
-	// linked=false means the account is not linked to any global user. When
+	// Identity boundary invariant: (platform, account_id) -> at most one
-	// several links exist for the same account (legacy duplicates), the oldest
+	// canonical global_user_id.
-	// (smallest linked_account id) wins — deterministic across retries.
+	//   - no rows            -> linked=false (account not linked; nothing created)
+	//   - one distinct global user -> that user; if several legacy link rows
+	//     exist for the SAME user, the oldest (smallest linked_account id) wins,
+	//     deterministic across retries
+	//   - more than one distinct global user -> FAILS CLOSED with
+	//     FailedPrecondition (ambiguous identity); callers must not persist
+	//     anything under a guessed identity
 	ResolveLinkedAccount(context.Context, *ResolveLinkedAccountRequest) (*ResolveLinkedAccountResponse, error)
+	// ResolveLinkedAccountByUsername resolves the global user owning a platform
+	// account addressed by its username rather than its id (e.g.
+	// platform="telegram", username="kaien"). Read-only: it never creates a
+	// global user or a linked account.
+	//
+	// Callers that only know how a person is addressed in chat need this; the
+	// id-based lookup above cannot serve them. Same fail-closed identity rule:
+	//   - no match                    -> found=false
+	//   - one global user             -> that user
+	//   - more than one global user   -> FailedPrecondition (ambiguous), so a
+	//     caller never acts on a guessed identity. Acting on the wrong one here
+	//     can mean phoning a person who never asked to be called.
+	ResolveLinkedAccountByUsername(context.Context, *ResolveLinkedAccountByUsernameRequest) (*ResolveLinkedAccountResponse, error)
 	mustEmbedUnimplementedUsersServiceServer()
 }
 
@@ -234,6 +283,9 @@ func (UnimplementedUsersServiceServer) GetLinkedAccountsByUserAndPlatform(contex
 func (UnimplementedUsersServiceServer) ResolveLinkedAccount(context.Context, *ResolveLinkedAccountRequest) (*ResolveLinkedAccountResponse, error) {
 	return nil, status.Error(codes.Unimplemented, "method ResolveLinkedAccount not implemented")
 }
+func (UnimplementedUsersServiceServer) ResolveLinkedAccountByUsername(context.Context, *ResolveLinkedAccountByUsernameRequest) (*ResolveLinkedAccountResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method ResolveLinkedAccountByUsername not implemented")
+}
 func (UnimplementedUsersServiceServer) mustEmbedUnimplementedUsersServiceServer() {}
 func (UnimplementedUsersServiceServer) testEmbeddedByValue()                      {}
 
@@ -435,6 +487,24 @@ func _UsersService_ResolveLinkedAccount_Handler(srv interface{}, ctx context.Con
 	return interceptor(ctx, in, info, handler)
 }
 
+func _UsersService_ResolveLinkedAccountByUsername_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ResolveLinkedAccountByUsernameRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(UsersServiceServer).ResolveLinkedAccountByUsername(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: UsersService_ResolveLinkedAccountByUsername_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(UsersServiceServer).ResolveLinkedAccountByUsername(ctx, req.(*ResolveLinkedAccountByUsernameRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // UsersService_ServiceDesc is the grpc.ServiceDesc for UsersService service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -482,6 +552,10 @@ var UsersService_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "ResolveLinkedAccount",
 			Handler:    _UsersService_ResolveLinkedAccount_Handler,
 		},
+		{
+			MethodName: "ResolveLinkedAccountByUsername",
+			Handler:    _UsersService_ResolveLinkedAccountByUsername_Handler,
+		},
 	},
 	Streams:  []grpc.StreamDesc{},
 	Metadata: "users.proto",